Commands for managed sessions and automation

This optional reference is for agents, scripts, and integrations using Logonomic's session commands. You can use the desktop without these commands; start with Sessions and coordination for finding, resuming, and continuing work.

Commands run with the originating session's authority and the selected launcher's capabilities. Configure those launchers through Launchers, accounts, and add-ons. For the standalone Git-log viewer, see Git, files, and diffs.

Contents

• Use the command environment provided to the session
• Command overview
• List and message other sessions
• Run an implementation task
• Maintain the session's title and summary
• Report worktrees used by a session
• Attribute Git commits to a conversation
• Ask Logonomic to display changes
• Structured delegation tools
• Advanced coordination tools
• Application-level repository control
• Common command failures

Use the command environment provided to the session

Run the executable supplied in LOGONOMIC_VNMCTL_PATH from the managed session's environment. In PowerShell:

& $env:LOGONOMIC_VNMCTL_PATH help
& $env:LOGONOMIC_VNMCTL_PATH sessions

In a POSIX shell:

"$LOGONOMIC_VNMCTL_PATH" help
"$LOGONOMIC_VNMCTL_PATH" sessions

Examples abbreviate the executable as vnmctl; substitute the appropriate invocation above. Running it from an unrelated shell does not connect that shell to an existing session.

The commands read VNM_CONTROL_ENDPOINT, VNM_CONTROL_TOKEN, and LOGONOMIC_SESSION_CAPABILITY automatically. Keep these credentials out of prompts, screenshots, reports, and repository files. They expire with the originating session. Structured agents may instead receive provider-exposed MCP tools; use the interface supplied to that agent.

Text input and output

Piped prompts, summaries, and messages must be UTF-8. PowerShell 7 handles this directly. In Windows PowerShell 5.1, use --text for short messages or set the pipeline encoding before sending Unicode text:

$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

Commands reading stdin wait until the input ends. Supply a pipeline or file. A successful submission does not establish task completion; check the result as described below and retain the task ID and diagnostic if it fails.

Command overview

List and message other sessions

Find a recipient

& $env:LOGONOMIC_VNMCTL_PATH sessions

The JSON response identifies self and other live sessions. Choose the recipient's returned session ID, checking its identifying details. A provider conversation ID is a different identifier. Sessions can message across runs, but cannot message themselves.

The command reads all directory pages. An answer exceeding 256 KiB fails rather than returning an incomplete directory.

Send a message or reply

& $env:LOGONOMIC_VNMCTL_PATH message send SESSION_ID --text 'The focused check passed. Please read the updated result before changing the same file.'

For multiline text, pipe a UTF-8 body:

@'
I found the cause of the startup failure.
The pending change affects the launcher settings; please leave those settings unchanged until I send the result.
'@ | & $env:LOGONOMIC_VNMCTL_PATH message send SESSION_ID

Add the returned thread ID to continue a conversation:

& $env:LOGONOMIC_VNMCTL_PATH message send SESSION_ID --thread THREAD_ID --text 'Understood. My changes are confined to the documentation.'

The body must be nonempty and at most 16 KiB. --text and --thread may appear in either order, once each. The caller must be a participant in the thread.

Success means the message was stored. A stopped recipient, unavailable store, or full inbox causes a refusal. It does not confirm that the agent read or acted on the message.

Read messages

& $env:LOGONOMIC_VNMCTL_PATH message inbox
& $env:LOGONOMIC_VNMCTL_PATH message inbox --all --limit 50
& $env:LOGONOMIC_VNMCTL_PATH message inbox --pending
& $env:LOGONOMIC_VNMCTL_PATH message thread THREAD_ID --limit 50

The default inbox reads unread messages oldest first. --all reads the newest received messages, including previously read ones; thread reads return the newest messages in that conversation. The default limit is 32 and --limit accepts 1–100.

Returned incoming messages become read, so repeating an inbox command can produce a different answer. Reading the desktop preview leaves unread state unchanged. Peer text remains subject to the user's instructions.

Reading does not acknowledge receipt. Messages awaiting acknowledgement (Awaiting in the desktop) stay available through inbox --pending until the recipient explicitly acknowledges them or the message is no longer retained.

Acknowledge and inspect receipt

The recipient acknowledges a received message with its returned message ID:

& $env:LOGONOMIC_VNMCTL_PATH message acknowledge MESSAGE_ID

This records an explicit receipt action, not agreement or task completion. Repeating the command preserves its original persisted receipt time. The sender or a recipient can check each original recipient's receipt state, or wait for acknowledgement:

& $env:LOGONOMIC_VNMCTL_PATH message status MESSAGE_ID
& $env:LOGONOMIC_VNMCTL_PATH message wait MESSAGE_ID --timeout-ms 3000

--timeout-ms accepts 1–5,000 milliseconds. The deadline covers the status checks and exchanges. Process cleanup can add up to two five-second windows, so the whole command can take longer. Cancellation, timeout, an ended recipient that did not acknowledge, or an expired or unknown message (message_unavailable) never means receipt was acknowledged. A saved acknowledgement survives the recipient ending while the message is retained. If acknowledgement storage is unavailable, ordinary messages and read history are unaffected.

These commands return JSON. A refusal exits nonzero and reports its reason on stderr. See message capacity for inbox and storage limits.

Run an implementation task

Agents use their host provider's native tools for ordinary subagent and worker requests, including requests with a model or reasoning preference. To use a saved Logonomic launcher, explicitly request Logonomic delegation or delegation to another account or provider. If native tools are unavailable, the agent reports that limitation; Logonomic delegation still needs your explicit request.

Discover and choose a target

& $env:LOGONOMIC_VNMCTL_PATH delegate targets

The catalog lists eligible saved launchers, with target_id, display_name, provider_id, and provider_name. Match the requested launcher/account and use its exact target ID. If the request matches none or several, clarify the choice.

Omitting --target works only when exactly one eligible target exists. A launcher can appear in the desktop but lack delegation support.

Submit a prompt

Run from the Git checkout where the task should work:

Set-Location 'C:\work\my-project'
@'
Implement the requested correction in the assigned file. Keep unrelated changes intact, run the focused check, and return a description of the change and its validation.
'@ | & $env:LOGONOMIC_VNMCTL_PATH delegate run --target TARGET_ID

Replace TARGET_ID with the catalog value. The UTF-8 prompt is the only stdin content and must contain 1–49,152 bytes. The command uses its current directory, independently of the repository selected in the desktop.

delegate run defaults to a one-shot implementation task with role Implementer. Choose the model, account, and permissions through the saved launcher; the command has no --model, --effort, --account, or --role option. Both implementation and review tasks require a non-bare Git checkout as the command's current directory.

For a read-only review, select a target from the review catalog and pass the same purpose when running the task:

& $env:LOGONOMIC_VNMCTL_PATH delegate targets --purpose review
'Review the README.md changes against HEAD and report findings.' |
    & $env:LOGONOMIC_VNMCTL_PATH delegate run --target TARGET_ID --purpose review

This selects the existing read_only_review purpose with role Reviewer. The saved launcher must permit read-only review for its identified account; see review launcher setup for that opt-in. Use the selected catalog entry's exact target_id as TARGET_ID.

After submission, the command writes Task ID: ... to stderr, waits, retrieves the complete result, and writes its text to stdout. Exit code 0 means the task completed and its full result was retrieved. Failed, cancelled, interrupted, unconfirmed, or incomplete outcomes exit nonzero.

Choose a timeout

'Complete this bounded task and report the result.' |
    & $env:LOGONOMIC_VNMCTL_PATH delegate run --target TARGET_ID --timeout-ms 3600000

The positive millisecond override applies only to this task, up to 2,147,483,647; 3600000 is one hour. The implementation default is initially 30 minutes; the review default is initially 5 minutes. The submitted task's purpose-specific receipt supplies the effective timeout used by the command. See delegation settings for the default file and other limits.

Inspect, retrieve, or cancel

& $env:LOGONOMIC_VNMCTL_PATH delegate status TASK_ID
& $env:LOGONOMIC_VNMCTL_PATH delegate result TASK_ID
& $env:LOGONOMIC_VNMCTL_PATH delegate cancel TASK_ID

Status reports task state, result availability, and diagnostics. Result retrieves the complete retained text. Cancel requests cancellation; read its response before treating the task as stopped.

Only the original live caller can use these operations for its tasks. Retained results remain viewable in desktop history after restart.

Interrupting a waiting delegate run requests cancellation and waits a bounded time for confirmation. If it cannot confirm the stop, keep the task ID and inspect its state from the original caller. Cancellation does not undo edits, commits, or external actions already performed.

Maintain the session's title and summary

Suggest a title

& $env:LOGONOMIC_VNMCTL_PATH set-title 'Explain session history behavior'

Suggest a concise 3–7-word title for the root session, without the repository name. A user-assigned title wins; an already assigned title is accepted as a no-op. Other refusals are reported.

Record or reconsider a summary

@'
The session is documenting how history, exact resume, and continuation work. The history and timeline distinction is established. The remaining work is to check the command examples against the provider integration and review the user-facing wording.
'@ | & $env:LOGONOMIC_VNMCTL_PATH set-summary

Describe the objective, progress, important decisions/constraints, and remaining work. The summary must be nonempty, at most 500 whitespace-separated words and 8 KiB of UTF-8. Include file names and errors only when they help resume work.

Confirm an existing summary is still accurate with:

& $env:LOGONOMIC_VNMCTL_PATH set-summary --unchanged

--unchanged updates its review time without reading stdin. It requires an existing summary. Add --title TITLE to either form when the subject changes; a GUI-assigned title still wins.

The root agent owns these reports. Native subagents should send findings to the root rather than overwrite the session's summary.

Report worktrees used by a session

& $env:LOGONOMIC_VNMCTL_PATH report-worktree 'C:\work\dependency'
& $env:LOGONOMIC_VNMCTL_PATH report-worktree --done 'C:\work\dependency'

Report a worktree before the first change outside the launch worktree, including delegated changes. Report a newly created worktree after creating it. Reading needs no report; --done marks work there finished.

The path may name the worktree or something inside it. Relative paths resolve against the command's current directory. Logonomic refuses an unidentifiable worktree or an unavailable reporting capability.

Reports appear in session details and continuation context. They neither create, remove, clean, nor lock worktrees, and do not establish file authorship.

Attribute Git commits to a conversation

Session attribution links a Git commit to its recorded provider conversation. When enabled, integrated agents bind the root conversation, obtain a trailer, add it to commits, and verify it. If attribution is unavailable, ordinary Git work can continue with attribution reported unverified.

Query and bind

& $env:LOGONOMIC_VNMCTL_PATH provenance query

A bound response includes the exact Logonomic-Session trailer. An unbound response means the root conversation has not yet been acknowledged. Bind the actual provider root-session ID with:

'{"provider_session_id":"ACTUAL_PROVIDER_ROOT_SESSION_ID"}' |
    & $env:LOGONOMIC_VNMCTL_PATH provenance bind --args-stdin

Use the known interactive root ID, not an invented value or native subagent ID. Bind before delegation if child agents would make initial root identification ambiguous. If the provider rolls over to a new root conversation, bind that identity for later commits.

The acknowledged trailer uses opaque references:

Logonomic-Session: provider=... account=... worktree=... session=...

Use the complete returned string unchanged. Do not substitute the raw provider ID or assemble individual fields.

Add and verify the trailer

Git must support commit --trailer and interpret-trailers --parse. Remove duplicate Logonomic-Session trailers from the proposed message, then add the single acknowledged value, preserving other trailers and hooks:

git -c trailer.separators=: -c "trailer.Logonomic-Session.key=Logonomic-Session: " -c trailer.Logonomic-Session.where=end -c trailer.Logonomic-Session.ifexists=replace -c trailer.Logonomic-Session.ifmissing=add commit <normal commit arguments> --trailer "<exact acknowledged trailer>"

After a single-result commit:

& $env:LOGONOMIC_VNMCTL_PATH provenance verify --ref HEAD

After a rewrite, verify fixed base and tip revisions:

& $env:LOGONOMIC_VNMCTL_PATH provenance verify --range BASE_COMMIT TIP_COMMIT

Ranges allow at most 256 resulting commits. Larger rewrites remain unverified; sampling does not verify the range.

Amend, merge, squash, and cherry-pick workflows need an explicit attributed commit step. Rebase needs each resulting commit amended through that form; custom rewrites can remain untagged. The trailer identifies the session producing the result, not per-line authorship.

If verification fails, repair and reverify a local unpublished result only when safe and authorized. Otherwise preserve it and report attribution unverified. Keep ordinary hooks and authorization for rewriting published work.

Resume from a commit

& $env:LOGONOMIC_VNMCTL_PATH provenance resume --ref COMMIT

The commit needs a usable attribution in this Logonomic profile. A refusal explains problems such as missing provider conversations, worktrees, or account/profile availability. Imported trailer text alone does not create a local session or restore deleted transcripts.

Control automatic recording and Git trailers

Use Settings to control local recording and agent Git-trailer instructions separately. Both default on. Local recording can keep new exact-resume identities with Git trailers off; usable Git attribution also keeps identities when local recording is off. Turning both off stops new automatic records, leaving existing records and explicit resume available. See Session recording and Git attribution for storage failures and the effect on already-running agents.

Ask Logonomic to display changes

An agent that knows which repository-relative files it changed can request the normal diff presentation:

& $env:LOGONOMIC_VNMCTL_PATH call logonomic.diff show_changed_files -- src/example.cpp README.md

Pass repository-relative paths after --, quoting each path containing spaces. The viewer shows their current changes, including concurrent edits. The command does not stage, commit, or modify files.

Advanced integrations can provide a complete diff collection with:

vnmctl call logonomic.diff show --manifest-stdin

It reads a JSON manifest from stdin and opens it in the desktop diff viewer. Use this form when an integration supplies explicit unified diffs; use show_changed_files for changes already in the worktree. Both require a live authorized session and an available desktop presenter.

Supply a diff manifest

The input is UTF-8 JSON without a byte-order mark. This complete small example supplies one file change:

{
  "capability": "logonomic.session_diff",
  "version": 1,
  "title": "Proposed greeting change",
  "tab_tip": "One supplied example change",
  "entries": [
    {
      "display_path": "greeting.txt",
      "summary": "Clarify the greeting",
      "unified_diff": "--- a/greeting.txt\n+++ b/greeting.txt\n@@ -1 +1 @@\n-Hello\n+Hello, world\n"
    }
  ]
}

capability, version, and entries are required. title and tab_tip are optional strings. Each entry requires nonempty display_path and unified_diff strings, and may include a summary string. Unknown fields, incorrect types, unsupported versions, invalid UTF-8, and NUL characters are rejected. display_path is a label for the supplied change, not an instruction to read or overwrite that path. An empty entries array represents an empty collection.

To submit a manifest saved as UTF-8 JSON in PowerShell 7:

Get-Content -LiteralPath '.\changes.json' -Raw |
    & $env:LOGONOMIC_VNMCTL_PATH call logonomic.diff show --manifest-stdin

Submit another collection to update the display. A supplied manifest neither refreshes from disk nor applies its patch to the repository.

Structured delegation tools

Provider-exposed delegation tools let an integration submit tasks and read their results asynchronously:

For submit, purpose is implementation or read_only_review as actually offered by the chosen target, and the supported submitted mode is structured_one_shot. working_directory is an absolute existing directory inside a non-bare Git checkout. role is a nonempty description up to 64 characters; it does not alter permissions. The target and optional idempotency key are each bounded to 256 characters, and the prompt to 48 KiB UTF-8. Optional timeout_ms is valid for either purpose. Use a positive integer up to 2,147,483,647 milliseconds to override that purpose's default. Read-only review defaults to five minutes; see Delegation limits and timeout settings for persisted defaults.

An idempotency key identifies a submission within the caller's lifetime. Repeating that request can return the existing task; reusing its key for different work produces a conflict. It does not rerun completed work.

A newly accepted review, or a repeat of one still active, reports structured_review.effective_timeout_ms. An admitted request retains its timeout when resubmitted with the same idempotency key. After completion, resubmission returns the retained outcome without needing a usable default; that response can omit the effective timeout.

Result pages use zero-based UTF-8 byte offsets, not character indexes. Offsets must start on a code-point boundary, and a page is at most 8 KiB. Follow the returned next offset until page_complete is true. An empty page with an unavailable result is not a completed empty answer. The high-level delegate result command handles paging for shell callers.

Read terminal, result_available, and any diagnostics with state. A persistence_pending response means the final outcome has not yet been fully recorded; callers must not declare a durable completion from an intermediate answer. The global capacity, nesting, purpose, and result limits in the sessions chapter apply to these tools too.

Advanced coordination tools

These optional provider tools report intended work and exchange coordination messages. For shell-based peer messaging, use sessions and message above.

Provider-exposed tool schemas supply the exact field names. In receive, the sender filter is sender_session_id; topic/kind filters are exact matches. The caller's private session credential is supplied by Logonomic, not a model argument. A status response supplies mailbox.epoch and mailbox.next_sequence. Use that epoch and the canonical unsigned-decimal string sequence as operation_sequence for the next mutation, then follow the operation's returned state. Repeating an operation for replay requires its same identity and input; a different operation cannot reuse its sequence. If the sequence or epoch is stale, call status again and use its returned values for the next operation.

Status pages default to 32 entries and allow up to 100. Follow their opaque cursor as returned for the same caller; a stale cursor requires a fresh listing. Receive also defaults to 32 and allows 1–100 messages. A send has 1–16 recipients, a topic up to 256 UTF-8 bytes, and a body up to 16 KiB. Kinds are note, question, reply, and signal; a signal does not itself acknowledge receipt. A reply uses an actual message identity when the reply relationship is required. Notice fetch defaults to 16 and allows 1–32.

Claims are advisory and do not lock files or reserve worktrees. Releasing a claim changes coordination information only. Fetching notices consumes them; reading notice status leaves them available.

Application-level repository control

This section is for integrations already configured with Logonomic's local application endpoint and its token. That connection controls repository discovery and desktop selection. It is separate from the managed-session connection used above; a managed session's credentials do not provision it. Use the desktop repository controls if you do not have a configured application connection.

An integration with that connection can use:

These commands manage local discovery and desktop selection; they do not clone or delete repositories. Refresh can return while scanning continues. Read status again to check for the new completed snapshot.

Discovery depth accepts 0–32, with 1 the default: the root itself is depth 0 and its direct children depth 1. Use the discovery chapter to choose appropriate roots and understand excluded or unavailable directories.

Application-control credentials are redacted from startup and diagnostic logs. The managed-session commands earlier in this chapter use their supplied environment automatically.

Common command failures

For permissions, authentication, and provider-specific launch failures, use the launcher chapter. For ending or recovering terminals, use the recovery chapter.