Skip to content

Troubleshooting

This guide helps recover from common issues when working with MCP Moira workflows.

Context Recovery After Session Archive

When a conversation is archived or compacted, the agent loses:

  • Current execution ID (processId)
  • Workflow step context
  • Progress information

The workflow state persists on the MCP server - only the agent’s memory is lost.

Recovery Steps

  1. Find active executions:
execution({ action: "executions" })

Returns list of executions with status, workflow ID, and notes:

[
{
"executionId": "abc-123",
"workflowId": "development-flow",
"status": "waiting",
"note": "Feature: auth system",
"currentNodeId": "implement-step"
}
]
  1. Get current step without advancing:
execution({ action: "current_step", executionId: "abc-123" })

Returns the current directive and context:

{
"attemptId": "attempt-current",
"directive": "Implement the feature...",
"completionCondition": "Feature working and tested",
"inputSchema": { ... }
}
  1. Continue workflow:
execution({ action: "step", processId: "abc-123", attemptId: "attempt-current", input: { ... } })

Process ID Preservation

To help future recovery, save the process ID in your workspace:

Terminal window
# Create process-id.txt in feature directory
echo "abc-123" > ./feature-name/process-id.txt

Include in session archives:

  • Feature name
  • Process ID
  • Current step description

session - executions

Returns one page of active workflow executions for the current user. Use limit and offset to read further pages; an empty page or missing row does not prove that an execution expired.

Call: execution({ action: "executions" })

Filters:

  • status: Array of statuses - ["waiting", "running", "completed", "failed"]
  • workflowId: Filter by specific workflow
  • search: Search in execution notes

Example with filters:

execution({
action: "executions",
status: ["waiting", "running"],
search: "auth"
})

session - current_step

Retrieves current step directive without advancing the workflow.

Call: execution({ action: "current_step", executionId: "..." })

Parameters:

  • executionId (required): Execution ID to check

Returns:

  • attemptId: Identity required to submit this exact current presentation
  • directive: What to do
  • completionCondition: Success criteria
  • inputSchema: Response structure

session - execution_context

Gets full execution state including context variables.

Call: execution({ action: "execution_context", executionId: "..." })

Parameters:

  • executionId (required): Execution ID to inspect

Returns:

  • executionId: Execution UUID
  • workflowId: Workflow being executed
  • status: Execution status (running, waiting, completed, failed)
  • currentNodeId: Current node ID
  • waitingForInputNodeId: Node waiting for input (if any)
  • taskTitle: Canonical task name, independent of the arbitrary note
  • taskIdentity: Persisted { title, changedAt, changeId } or null
  • revision, metadataRevisions.taskIdentity: Step and independent task-name revision
  • note: Arbitrary execution note
  • context.variables: Context variables
  • context.nodeStates: Node execution states
  • createdAt, updatedAt, completedAt: Timestamps
  • error: Error message (if failed)

Common Issues

“Process not found or expired”

Cause: The supplied identity is unavailable to this caller. This alone does not establish expiry, deletion or the outcome of an earlier operation.

Solution:

  1. Use execution({ action: "executions" }) to find active executions
  2. Use the correct executionId from the list
  3. Process IDs are UUIDs like abc123-def456-...

“Execution is not waiting for input”

Cause: Trying to advance a completed or failed execution

Solution:

  1. Check execution status with execution({ action: "execution_context", executionId: "..." })
  2. Inspect the actual waiting node and current presentation; a persisted running execution can be waiting for input. Do not infer readiness from a display status alone.
  3. A terminal execution cannot be advanced. Start another only for a deliberate new task, never to collect or retry an uncertain original effect.

Step validation errors

Cause: Input doesn’t match inputSchema

Solution:

  1. Check inputSchema from current step
  2. Verify field names match exactly (case sensitive)
  3. Verify data types match (string vs number)
  4. Include all required fields

ATTEMPT_PROCESSING

Cause: Another caller still has a live claim on this exact step mutation.

Solution: Retry with the same Process ID, Step attempt ID, and input. Do not replace the attempt or alter the input.

ATTEMPT_STALE

Cause: The attempt no longer matches the current execution presentation and was rejected before handler work.

Solution: Read execution({ action: "current_step", executionId: "..." }), then reconcile its node, directive, schema and current intent before submitting with that attempt. Do not reuse the stale ID, carry old input into another step, or overwrite a newer user answer.

ATTEMPT_CONFLICT

Cause: The attempt is already bound to a different input and the new submission was rejected before handler work.

Solution: Automatically call execution({ action: "current_step", executionId: "..." }), discard the conflicting attempt, and continue from the returned directive and input schema. Do not replay the rejected input against the current presentation.

ATTEMPT_INVALID_OR_EXPIRED for a step

Cause: The step attempt is unavailable and was rejected before handler work. This recovery applies only when the error explicitly directs the caller to current_step; an unavailable start attempt has no current step to recover.

Solution: Automatically call execution({ action: "current_step", executionId: "..." }), discard the unavailable attempt, and continue from the returned directive and input schema.

ATTEMPT_OUTCOME_UNKNOWN

Cause: Moira could not prove whether a claimed mutation and its possible external effect completed.

Solution: Inspect the execution with execution({ action: "current_step", executionId: "..." }) and the relevant external system. Do not automatically retry the mutation.

CURRENT_PRESENTATION_STALE

Cause: The persisted live attempt belongs to a different node, or to a continuation surface the current definition no longer has: something the paused node declares about what it does changed, or a registry entry for a global variable it declares as an input did. It cannot be safely rebound to the current execution. A change that does not reach that surface does not produce this state — a version or tag bump, an edit to another node, or a cosmetic change to the paused node itself all leave the run usable.

Solution: Do not retry the old attempt. Call execution({ action: 'diagnose', executionId: '...' }), which names which facts of the paused step changed, whether its node still exists, and anything else standing between the run and its next step. Then repair the run with execution({ action: 'recover', executionId: '...', nodeId: '<node to resume from>', variableValues: { ... } }), which re-presents it at the node you name with the values that step needs and returns a fresh Step attempt ID to continue from. Name a node a run can wait on — an agent-directive, teleport, materialize, lock or subgraph node; any other node is refused, because resuming there would run the workflow forward instead of repairing it. The run comes to rest on the node you name and never goes past it, but a lock node creates its lock and sends its approval code when the run arrives there, and a subgraph node enters its child — choose one of those as the target only when you want that. Recovery is also refused unless the run really cannot continue, and refused for a run that is already finished or cancelled, which stays that way; a refusal changes nothing. For a materialize target, recovery keeps the execution paused there. Perform its generated delivery to obtain the current guide files; a context patch alone does not refresh local files.

A task-name write is stale

Read execution_context again and reconcile the actual task before retrying update-task-title with its current step and identity revisions. A same-clock rename back to the original text still invalidates the older identity revision. Do not bypass the guards or use a note as a title; see execution task naming.

STEP_BLOCKED or RECOVERY REQUIRED for a missing expression variable

Cause: The current agent-directive node has an expression that needs saved execution state. The named variable is absent, and Moira can establish that no answer field accepted by the input schema and declared as a node output can provide it. An open input schema does not make undeclared answer fields usable. A declared field is also unavailable when the input schema structurally forbids it, such as with maxProperties: 0, a false property schema, or an allOf prohibition. When the schema does not prove a prohibition, correct an invalid answer through the normal retry. This can happen when the workflow definition changes while an execution is in progress. A recorded error by itself is historical; the current missing value is what blocks continuation.

Solution: Call execution({ action: "diagnose", executionId: "..." }) and check for the blocking missing_expression_variables cause. Call execution({ action: "recover", executionId: "...", nodeId: "<current node>", variableValues: { ... } }) with the named values. Values for declared variables must satisfy their registry schemas; execution({ action: "variables", executionId: "..." }) shows those declarations. If recovery refuses a missing or invalid value, correct variableValues and retry; a refusal does not change the execution. On success, use the new Step attempt ID to send the ordinary answer to the same node. Do not retry an unchanged answer while the saved state is missing. If the submitted answer fails an earlier expression for its own reason, correct that answer first; diagnose may still name a later missing saved value that needs recovery. A node’s authored error route remains in force.

Agent Forgets Workflow Context

Cause: Session was archived/compacted

Solution:

  1. Check for process-id.txt in workspace
  2. Use execution({ action: "current_step", executionId }) with the retained identity to get context
  3. Remind agent: “Continue workflow {processId}”

Seeing [[UNDEFINED_VARIABLE]] in a directive at runtime

Cause: A referenced value was unresolved when the directive was rendered. Check:

  1. The variable is not declared in variableRegistry.
  2. The variable is declared but has no default and was not yet written by an upstream node before the directive used it.
  3. A node-local output is absent or referenced by a bare name instead of node-id.field. Optional null values also render the placeholder when substituted directly.

The engine logs a warning naming the residual placeholder and the executionId.

Solution:

  1. Use a declared global or the actual node-local path; seed a meaningful default only when the contract has one.
  2. Ensure the producing node runs before use; guard optional text instead of manufacturing evidence.
  3. Returned step data is literal and is not re-scanned as templates. Braces inside returned source code or examples are valid data; authored dynamic behavior belongs in template-enabled static fields.

Editing files while a command runs

A running command or development server does not itself block codespace_edit (create), codespace_edit (replace), codespace_edit (patch) or codespace_upload. Supply expected complete text or a returned file reference for replacement. If another writer changes the file, reread and reconcile before a new explicit edit. Do not calculate a digest of a selected byte range as a whole-file precondition. Commit and recovery use the guest’s confined atomic transactions; recovery never overwrites a later edit.

Large files and rejected file operations

For COMMAND_CWD_OUTSIDE_WORKSPACE, use cwd: "." for the selected repository root or an existing directory inside it, such as moira-ws/task. COMMAND_CWD_NOT_FOUND requires creating that directory from cwd: "." first; COMMAND_CWD_NOT_DIRECTORY requires selecting a directory instead of a file. For COMMAND_CWD_UNAVAILABLE, check its access permissions. These responses confirm that the command did not start; its returned operation remains collectable.

FILE_REJECTED with reason: "unsafe_access" requires a repository-relative file path without an absolute prefix or ... File tools refuse symlinks and unsupported file types. A directory created elsewhere in the VM is outside this boundary. Use commands from cwd: "." to create moira-ws/task, then address its files as moira-ws/task/file.md. For precondition or concurrent_change, reread the file and reconcile the intended edit. If a mutation returned an operation reference, inspect that original before choosing another action.

Use codespace_read (stat) for metadata and codespace_read (read) with line windows or its returned cursor for text. Continuation preserves complete UTF-8 characters; Cyrillic or emoji split across an internal byte boundary is not a binary file. Use codespace_download for complete binary bytes. Name and MIME are derived when omitted; no preliminary stat is required. Empty downloads are supported. codespace_read (preview) returns complete valid PNG/JPEG content, not SVG or an image prefix. Its structural validation is not proof that a browser ran or that the screenshot is visually correct. Optional max_bytes is the caller’s selected bound, not a shared transfer quota.

Commands and files remain subject to storage, current owner authority, repository/path safety and expected-content checks. Native descriptors stream to the owner without base64. The direct ~/.local/bin/moira-workspace CLI uses the same Unix owner without requiring a cloud connection; fixed bootstrap updates the service in place without replacing the VM or its disks.

communication (deliver) accepts a native file at a selected controller; communication (deliver_publication) sends an owned file.reference_id. The optional channel selects a configured channel, never a recipient. Publication does not send a message, delivery neither consumes nor renews it, and expiry requires a separate intentional publication. File-capable extensions use their declared binary transport.

Keep the returned operation, including an attachment notification’s workflow result. communication({ action: "collect", reference }) never uploads, renders or sends again. A closed uncertain owner outcome projects as unconfirmed even if its private receipt is terminal; a confirmed refusal remains completed with outcome.ok:false. One channel can remain uncertain after another succeeded. Discovery returns references and safe metadata, not full outcomes; collect the selected original explicitly. If the first reply was lost, use communication (find) at the selected owner and choose a candidate deliberately. Neither one candidate nor no candidate proves which effect occurred. Never create a new delivery merely because collection is absent, unavailable or unconfirmed.

For COMMUNICATION_OWNER_UNAVAILABLE, restore the selected controller or guest route rather than choosing a different owner. Ordinary text remains independent. A materialize archive’s HTTP 409 COMMUNICATION_OUTCOME_UNCONFIRMED is collected through the same grant URL; it cannot resubmit or change owners. HTTP 422 reports an owner error and HTTP 503 an unavailable controller. Do not complete a workflow step without its files. A fresh current_step presentation is an explicit separate attempt; the execution (materialize) text fallback requires no file owner.

GitHub setup and remote readiness

Provider available, verified local Unix readiness and a live remote route are separate facts. The guest CLI can work before first enrollment completes. Remote command/file tools require a current enrolled connection; a saved running observation alone does not provide it.

For initial unconfigured or enrollment_unavailable remote state, first collect the original operation and settle its scoped SSH custody. If CODESPACE_LOCAL_SETUP_INCOMPLETE remains on a known GitHub environment, restore the selected controller and current GitHub access, then choose Resume setup or use codespace({ action: "lifecycle", workspace, operation: "resume_setup" }) with its returned workspace reference. The controller uses the saved original root/repository, guest life, installed release and assignment proof. It performs fixed configuration and enrollment without provider start, payload installation, adoption or another VM. Missing proof or changed life, generation or authority refuses continuation. Collection itself never enrolls or opens SSH.

An already enrolled guest’s connecting or unavailable transport uses its existing reconnect loop; do not use setup continuation to replace that authority. After a genuine cold life change, retained renewal authority allows the Unix API to become ready before remote renewal. Network and store failures retry the same durable renewal request; old-life credentials cannot open a connection. Confirmed refusal requires authority repair and leaves locally authorized work available. A guest that never enrolled cannot renew or regenerate its original proof after a life change. Preserve its state and inspect the original with the assigned controller.

Later enrollment or renewal attaches to the same running Unix owner without replaying commands. A cold restart can interrupt processes and does not promise uninterrupted command execution.

Local codespaces

Local and GitHub lifecycle requests can return pending while the controller continues startup, setup or shutdown. This confirms durable acceptance, not completion. Retain operation and use codespace({ action: "collect", reference: operation }) or host collect OPERATION_REF. The response includes collection guidance and, when recorded, original.phase with the last owner stage; this is not a progress percentage or a fresh VM observation. Do not submit another create/start/stop/delete to check progress. A lost reply or unavailable live owner can instead leave the outcome unconfirmed: collect the same original, or use codespace (find) at the selected controller if its reference was lost. Neither a timeout nor an absent result proves that the effect did not happen.

Use codespace_terminal (run) or codespace_terminal (run_native) with the returned workspace reference. The adapter creates internal request identity; do not manufacture UUIDs or process IDs. A live command may return before completion. Use its operation for codespace_terminal (collect), and its process for codespace_terminal (output) or explicit codespace_terminal (stop). Observation does not cancel work; pending cancellation is not a confirmed physical stop. Deliberately identical commands are distinct intentions. An uncontrolled first reply has no automatic deduplication guarantee.

The guest owns command receipts and retained stdout/stderr. Collection requires the service and retained guest data; cloud storage does not provide a second copy. Operation identity, input digest/comparison metadata and original results remain retained. Only a verified temporary native/stdin copy can be removed after a matching terminal result and settled input readers; live, unknown or conflicting work retains it. Collection does not reacquire the source or repeat the action. A cloud disconnect does not cancel a guest command. VM shutdown, provider idle stop or reboot can interrupt it. Missing or archived legacy receipts are not replayed. Preserve existing UNKNOWN records for diagnosis rather than importing their IDs into the new namespace. Explicit command deadlines and client wait bounds are separate.

Guest daemon diagnostics are in ~/.local/state/moira/workspace-service/daemon.log, daemon.log.1 and daemon.log.2, each bounded to 1 MiB. Their rotation does not trim command stdout/stderr. Read complete command streams with codespace_terminal (output) or moira-workspace output "$PROCESS_REF" --stream stdout (use stderr for that stream). Preserve journals and unresolved input when diagnosing an owner failure.

Workspace routing for both GitHub Codespaces and Local requires a live, already prepared and enrolled owner service. Start the resource and complete its provider preparation explicitly before calling workspace tools. An unavailable owner returns CODESPACE_PROVIDER_UNAVAILABLE before dispatch; routing does not implicitly start a VM or perform cloud bootstrap. A disconnected computer requires restoring the companion connection. CODESPACE_PROVIDER_DISABLED indicates disabled GitHub provider configuration. Local work uses its owner’s grants, enabled permission and physical capacity rather than cloud operational controls. For GitHub create/start/adopt, reconnect the assigned paired controller; remote guest access also requires authenticated outbound registration. Configuration ready alone does not prove that. A confirmed registration 401/403 requires current authority repair; temporary network loss can reconnect the same valid identity without replaying the original operation.

CODESPACE_AUTHORIZATION_REQUIRED requires restoring actual account, device or repository access in Settings. The host CLI supports create OWNER/REPO --ref BRANCH, start WORKSPACE_REF, resume-setup WORKSPACE_REF, stop WORKSPACE_REF, remove WORKSPACE_REF --confirm, collect OPERATION_REF and operations CONTROLLER_REF through the running private controller. Raw host execution is unsupported. Privileged maintenance and security requests retain their separate collect ORIGINAL_REQUEST_ID path; this is not raw lifecycle submission. Fresh create requires cloud registration and initial Git authority. Already admitted VMs remain subject to current local authority offline.

Use codespace (targets) to obtain the selected controller and personal installation references. codespace (repository_admit) requires current applied existing-private consent and an App-accessible repository owned by the connected personal account. It cannot broaden rights; a pending settings revision must settle first. codespace (repository_create) requires new-private consent. Organization installations and public creation are unsupported.

Preserve the returned original operation. codespace (collect) is read-only; after fixing permissions, installation access or admission, codespace (resume) explicitly continues only the original private-repository creation. It does not restart commands or create a replacement repository. setup_required can retain a confirmed repository while admission remains incomplete. Unknown creation checks the retained description marker; an unrelated same-name repository or missing observation cannot settle it. Do not remove the marker while unresolved. A rejected admission can leave the repository on GitHub: restore its grant in Settings or request existing-private admission when the owner permits it. A rejection does not authorize another create.

Use Settings → Development → Local computers and the companion’s status to distinguish pending browser approval, revocation, an offline computer and disabled local work. An offline row is not proof that the computer or its VM has physically stopped. Enable work on the computer with npm run local -- enable; it remains permitted until explicit disable. Use npm run local -- install to stage the complete owner release and register login startup, then npm run local -- run to start or connect to it. The persistent host owner holds VM custody and the broker/tunnel; this client exits without stopping them. Ordinary installation stages a release without replacing a running owner. npm run local -- service-status reports its running release, readiness, cloud connection, staged release and startup failure. A failure restoring Local VMs does not close the paired controller or its file publications and original-operation collection. Native ready: false can coexist with a connected controller; inspect both rather than treating a Docker refusal as an unavailable file owner. Pairing authority and route reachability remain required. A confirmed controller shutdown reports offline; an unresolved shutdown reports faulted. A revoked device requires a new pairing and browser confirmation. Open that computer’s codespace card and use Check state again for a pending start, stop or delete. It collects the original lifecycle receipt when its identity is known, otherwise it performs a read-only refresh. It never resubmits start/stop/delete or creates a replacement VM. That refresh observes only the selected VM. Errors and loaders stay on the affected card. A collected successful result can describe the operation’s historical observation. It remains confirmed if a subsequent read fails, but does not authorize another lifecycle action. Use Check state again to obtain current state before making that next decision. For both Local and GitHub, collection returns the same public workspace shape as the immediate result without another full scan. If the confirmed receipt cannot provide that snapshot, the UI shows Original operation completed and retains the same original for another check. The API returns outcome:{ok:true,result:null} with a separate safe observation_error; this is not an unknown effect or permission to create again. A lost first create reply needs no existing card to retain its confirmation. Current account/controller authority is still required: revocation during collection refuses the response even when the private operation completed. Restore the permitted access and inspect that same original rather than repeating the effect. Delete is available with confirmation during pending creation, cleanup or uncertain local state when a current summary supplies a returned workspace reference. Unavailable identities have no lifecycle controls. Deletion targets that same captured observation and completes only after confirmed absence. Owner cleanup needs active pairing, local web control and a reachable owner, but not agent delete permission or enabled work; it changes neither permission. MCP deletion retains its agent grant and enabled-permission checks.

A refusal stays in the confirmation dialog and ends its spinner. Cancel remains available. A background refresh does not replace the captured delete target. After inspecting a different observation, make a new explicit confirmation; an automatic retry must not refresh preconditions. An operation’s 403 refusal does not sign out the owner; session expiry and account admission errors retain their authentication handling. Do not clear journals, edit database state or create a replacement to bypass an unresolved removal.

observed_at in a codespace summary is the last verified provider observation, nullable until one succeeds. updated_at is bookkeeping time and does not prove runtime freshness. lifecycle_error is a safe diagnostic code, not raw provider output. A failed scoped observation preserves the verified state/time and does not prove absence. Healthy sibling VMs still refresh and run. Physical startup alone does not mean guest preparation completed. A local created VM remains actionable but needs independent native settlement before stop completion; an SDK error does not itself complete a local stop. Before Local create/start/stop/delete, use the returned target/workspace references unchanged. Lifecycle conflicts require a fresh observation and explicit decision, not an automatic refreshed-precondition retry. codespace (collect) collects the retained original; pending_operations restores collection after reload. A lost first reply instead offers codespace (find) on the selected controller, with explicit candidate selection. absent or newer metadata does not re-enable an uncertain mutation.

Cloud registration is a route, not a machine observation. codespace (observe) can report CODESPACE_PROVIDER_UNAVAILABLE without inventing state or generation. Call codespace({ action: "list", provider: "local-sandboxes", view: "diagnostics" }) for Local diagnostics, or select provider: "github-codespaces" for GitHub. The normal actionable list keeps current useful environments and known incomplete setup; diagnostics preserves uncertain or unavailable identities, safe errors and original-operation references without lifecycle generations. has_diagnostics points to retained diagnostics; view: "history" exposes confirmed retired environments. A selected-provider failure is not an empty inventory, and Local does not await GitHub or billing. Device/settings reads and exact repository Git authorization do not await all-VM native inventory. They still require current owner policy and binding; reachable management or a healthy heartbeat does not prove guest readiness or physical VM state. A pending settings request is not applied permission. Repository/controller choices and VM inventory load and retry independently; a delayed inventory does not remove the creation form or its draft. An authority or response-schema failure belonging to one computer makes its owner observation unavailable without hiding healthy computers or accepting its untrusted policy. An account-wide admission failure still refuses the request. In Settings, select Diagnostics or History for that provider; billing has its own read and retry in the GitHub subsection. A pending unknown creation remains collectable as its original operation, not a replacement VM. A nullable machine is not a default profile or permission to start.

For Local CODESPACE_LOCAL_SETUP_INCOMPLETE, repair the reported prerequisite and choose Resume setup, codespace({ action: "lifecycle", workspace, operation: "resume_setup" }), or host resume-setup WORKSPACE_REF. This prepares the same known VM and preserves its files and original create outcome. Ordinary Start and custody recover do not resume setup. The optional setup_failure guides preserved-root inspection (repository_unproven), Python3/libc/exclusive-publication prerequisites (prerequisite_unavailable), repository access/ref repair (repository_checkout_failed) or fixed configuration diagnostics (configuration_failed). Unknown creation or guest settlement still requires original collection, not adoption by name. An owner-confirmed custody acknowledgement preserves incomplete setup; explicitly resume it afterward.

Preparation retains an exact setup-attempt identity and links its security requests before issuing credentials. If the safe failure asks for original security collection, inspect moira-local status --json and use moira-local collect ORIGINAL_ID for those requests before explicitly resuming that same VM. Collection does not retry checkout. Older security originals without that association must be inspected by their known IDs; do not infer a match from time, repository or pending state. Unavailable authority, unconfirmed credential custody and a confirmed checkout/ref refusal require different repairs. Without exact evidence the diagnostic names the failed phase rather than claiming a GitHub refusal. Unknown physical execution retains its settlement/recovery requirement; a logical checkout refusal alone does not require stopping or recovering the entire VM.

For CODESPACE_LOCAL_PROTOCOL_ERROR, coordinate matching server/companion builds and preserve saved identity and journals. For CODESPACE_LOCAL_RUNTIME_ERROR, repair the actual runtime and observe the same workspace again; the error does not imply shutdown. CODESPACE_LOCAL_DELETE_APPROVAL_REQUIRED requires owner confirmation in Settings → Development → Local computers with active web control, not a permanent agent-delete grant.

With locally approved web-control, request settings within the resource ceilings in the device editor. Pending means the computer has not applied the request; rejected shows the refusal and retains the last successfully acknowledged revision. A failed application can disable work in the reported policy; that revision alone does not mean work remains enabled. An offline computer exposes no current policy or grants. Saving is refused and the settings draft remains in the editor; reconnect and refresh before explicitly saving. An already accepted settings request retains its original identity for collection, which cannot repeat the effect. An original historical success may have no typed current device projection; refresh current owner settings separately rather than submitting the change again. Ordinary label/grant/Git-identity and new-VM-default edits apply live when enablement and shared storage are unchanged. Existing admitted VM profiles remain intact; changing enablement or shared storage uses the physical transition. Git author changes update policy; repository-local Git config uses the value during workspace preparation. Saving the setting does not force a rewrite in an already running checkout.

The daemon reports connected, offline, faulted or disabled in its structured stderr status. Network/5xx failures make remote owner state unavailable without stopping admitted VM work. New remote mutations are refused rather than queued. An addressed resource refusal returns a bounded error for that request; a lost reply to an accepted effect requires original receipt collection. Device-endpoint unauthorized responses or confirmed device identity/revocation failures retire the remote route without turning local VM intent into stop. Local disable and explicit physical stop remain independent controls. Current grants remain enforced. Cached results can return without repeating effects; an offline row cannot promise immediate delivery of a remote revocation.

Git and PR requests execute directly in the trusted owner’s fixed broker. Original OAuth/refresh credentials remain server-side; a broker child is limited to the approved repository/action. SCOPED_CREDENTIAL_OUTCOME_UNCONFIRMED, SCOPED_CREDENTIAL_CUSTODY_UNCONFIRMED and SCOPED_CREDENTIAL_DISPOSAL_PENDING require collection of the original security_request_id. On the Local host use moira-local status --json and moira-local collect ORIGINAL_ID. Pure collection cannot mint a token, replay Git or cancel a live stream; absence does not authorize automatic reissuance. A refused issuer never enables a host-token fallback.

For an unknown PR create, retain its operation and collect with codespace_git (collect) or guest moira-workspace get OPERATION_REF. Use codespace_git (read) or pr-find HEAD BASE to inspect that head/base before a deliberate new create. Do not call codespace_git (create) again to collect. A pre-dispatch PR refusal can coexist with uncertain credential custody; follow the separate privileged security collection without issuing another token.

Account block or resource retirement can retain a scoped-disposal error without provider stop completion. Account deletion returns ACCOUNT_CREDENTIAL_RETIREMENT_PENDING or ACCOUNT_RESOURCE_RETIREMENT_PENDING while the account stays blocked and cleanup keys remain. Explicitly delete owned managed resources through their confirmed cleanup before requesting deletion of the account; stopping a persistent VM does not remove its disk, and account deletion does not do so implicitly. Revoking a Local device or resource binding also does not confirm deletion. Unretired historical resources, including those without a binding or with an unknown native outcome, retain their ownership witness and keep account deletion pending until the exact resource is confirmed retired.

A Git identity HTTP 401/403 can safely direct the owner to refresh repository access, add this repository to the App installation, or reconnect the verified GitHub identity in Settings. Other response text remains private; a refusal never permits using a host token or widening rights. The proxy authenticates package requests with its installed per-space broker permission; package clients need not send a proxy-auth header. The host still enforces the computer’s enabled permission, repository authority and public-address/computer-network checks. A proxy refusal is not permission to broaden them or use a host/GitHub token. Local CONNECT timeouts guard establishment. After the fixed broker connection and verified upstream connection are established, these guards no longer impose an idle deadline. Current permission, revocation, socket closure and broker shutdown still end access. Public destinations are independent of technology; network downloads have no cumulative traffic or per-response byte, connection-count or established-transfer duration quota. Host, LAN and service destinations remain denied.

doctor requires enabled work permission and checks prerequisites, not live VM isolation. Its bounded diagnostic window does not establish settlement of pending work. Current authority is checked while SDK startup is pending; installation and registration have no general work deadline. Device active/enabled and setup ready describe authorization and configuration, not a successful guest connection. A working guest Unix API is ready before optional workspace-credential acquisition and can remain ready while remote access is not. A held cloud reply does not hold local work/lifecycle admission; current runtime, generation, grant and connection are revalidated before applying it. Each VM has at most one active enrollment attempt; a held response for one VM does not delay another VM’s attempt or its retry after a confirmed failure. This does not replay commands or bypass current authority. Warm preparation uses configured or exact retained author data; public checkout does not depend on optional Git author lookup. Initial private checkout still requires current authority. Optional observed remote.state is unconfigured, enrollment_unavailable, connecting, connected, unavailable or refused; missing observation is unknown. Enrollment unavailability needs current registration to become available; an existing unavailable transport reconnects with the same authority. Temporary network/store failure is not confirmed revocation. A confirmed refusal closes that remote authority without stopping locally authorized work. Later enrollment updates the same Unix owner without replaying accepted commands. Check the current diagnostic when guest calls time out. After login or a cold owner restart, the installed service restores intended work for the same known VM identities and disks when runtime, credentials and current work permission are available. run starts or connects to that owner. Recovery reclaims a stale runner marker only when its runner and guard are proven absent under the system lock. It preserves saved work and never replays accepted commands or unknown operations. A host reboot can interrupt commands and requires fresh kernel custody; it is not uninterrupted execution. Live or unverifiable owners remain refused; do not clear their lock or receipt to bypass the check. If the default macOS storage mount is absent after reboot, inspect service-status with the same state. Startup attaches only its existing owned storage.sparsebundle, verifies the native mount binding and repeats volume ownership and approved capacity admission without a fixed free-space reserve. A lost attach reply is resolved by observing that binding. LOCAL_STORAGE_NOT_MOUNTED means storage remains unavailable: mount a custom volume manually, or check that the saved default image is present and can be mounted. LOCAL_STORAGE_OWNER requires resolving an unsafe image/mount or conflicting binding. Preserve the image and state; startup never creates a replacement disk or resets data to bypass a refusal. After repairing a startup prerequisite, repeating run while the failed service endpoint remains reachable only prints its retained status; it does not retry initialization. If no owner is running, run starts the selected owner instead. If the original maintenance receipt remains in phase selected for this running release, repeat that original intent with maintenance --request-id ORIGINAL_ID --confirm; for an original pause, use maintenance --resume --request-id ORIGINAL_ID --confirm instead. This restarts the failed owner without repeating its already confirmed physical stop or selection. Keep collecting the same ID; only the successor’s recovery result confirms completion. Other unconfirmed maintenance phases still require the physical-settlement repair described below; they do not qualify for this startup-only retry. If there is no unresolved maintenance request, explicitly restart the active release with maintenance --pause --confirm, retain its ID, collect until paused, then use maintenance --resume --request-id ORIGINAL_ID --confirm. This pause needs no newly staged release and declares physical interruption. Use run if needed to start the selected owner, then check service-status and the original receipt. Keep the same --state PATH throughout; do not edit locks or sockets, replace pairing, or replay interrupted commands.

If maintenance remains accepted with LOCAL_CUSTODY_UNCONFIRMED, the controller has not yet confirmed closure of an earlier provisioning process. It keeps original-operation discovery and collection available while refusing new work. Use the retained controller reference with npm run local -- operations CONTROLLER_REF --kind lifecycle, inspect the candidates, then run npm run local -- collect OPERATION_REF with the selected returned operation reference. Once collection confirms closure, continue the same maintenance action and ID; for an original pause use npm run local -- maintenance --pause --request-id ORIGINAL_MAINTENANCE_ID --confirm. Keep the same --state PATH. Do not replace the request ID or run login until the original reports paused; an accepted request with an error does not prove physical shutdown.

For LOCAL_DOCKER_LOGIN_REQUIRED, the saved authentication refusal blocks native startup before credential access. Installing or restarting the owner preserves it; communication does not require repairing Docker sign-in. To restore native work, use an explicit maintenance pause and the existing credential store:

Terminal window
npm run local -- maintenance --pause --confirm
npm run local -- collect ORIGINAL_MAINTENANCE_ID
# Continue only after this original reports paused.
npm run local -- login
npm run local -- maintenance --resume --request-id ORIGINAL_MAINTENANCE_ID --confirm
npm run local -- run
npm run local -- service-status

Keep the same --state PATH on every command when configured. Login can require Keychain access or Docker browser sign-in; it is an explicit owner action, not a background file-transfer repair. Do not use --new-store or delete the failure record to bypass this refusal. Only successful same-store login clears the exact authentication failure it observed. Collect that same maintenance ID and inspect its VM recovery result; completed maintenance can still report unavailable VMs without replaying their interrupted commands.

If the companion reports LOCAL_STORAGE_FULL during shrink, the requested size cannot preserve existing data or the native APFS minimum. Check the computer’s shared backing-image capacity and actual disk space separately from free space on the Mac; admission imposes no extra reserve. To raise its approved maximum, pause the physical owner explicitly and retain the printed maintenance request ID. Wait until collection reports paused before changing local approval:

Terminal window
npm run local -- maintenance --pause --confirm
npm run local -- collect ORIGINAL_MAINTENANCE_ID
npm run local -- web-control --confirm --storage-gib 50
npm run local -- maintenance --resume --request-id ORIGINAL_MAINTENANCE_ID --confirm
npm run local -- run

Use the same --state PATH on every command when configured. Collect the same maintenance ID until its result is known; pause/resume declares physical interruption and restores saved intent, not the interrupted commands. Closing a client or pressing Ctrl+C is not this pause. Do not use disable just to revise the maximum, since it disables and stops owned work. Omitted limits retain the existing approval. Refresh Local computers, request Storage 50 in the computer’s editor and wait for the applied revision and actual capacity. Approval itself does not resize storage, enable work or clear a pending request. A failed or interrupted resize keeps its existing recovery records; do not reset state or recreate codespaces. Disabled work does not prevent management from reporting the approval, but guest work still requires valid work permission. If the approval reply is lost, reconnect with the same state so the same saved approval is reported again. Direct local login, setup, recover and web-control approval require the physical runner gate. With an installed owner, use the same explicit maintenance pause/resume boundary before those commands; the paused service retains its management endpoint while releasing physical ownership. Unsupported SDK versions, Linux runtime ownership, unsafe mounts/settings or unknown identity refuse work; do not reset the personal Docker profile, substitute an ordinary directory for bounded storage, or relax network policy. For Docker sign-in use npm run local -- login. An unreadable SDK store can be recovered explicitly with login --new-store only after local disable and owned shutdown; existing stores are preserved.

For an owner update, stage the complete package with install, inspect service-status, then request maintenance --confirm. Retain its printed request ID and use collect ORIGINAL_ID after a lost reply. The owner settles exact physical custody before selecting the staged release; kernel settlement validates the captured profile, absence of its former owner and unchanged policy/custody records, even when no native observer was acquired. Closing the controller or releasing an observer does not establish physical shutdown. The successor restores the same saved VM identities, disks and intended running state. Accepted commands are not replayed, and commands interrupted by maintenance may have uncertain outcomes. If settlement is unconfirmed, no replacement owner starts. Preserve the receipt and resolve the physical refusal; do not issue another stop or replace the maintenance identity. After an explicit recover --confirm of the disabled device, resubmit that same maintenance intent to check its fresh settlement proof. Pure collection does not perform recovery. An incompatible client reports LOCAL_SERVICE_MAINTENANCE_REQUIRED rather than replacing a live owner.

After an update, a strict heartbeat or web-control.json rejection can mean the server, companion and owner guard use different control-contract editions, even with delegation disabled. Rebuilding the CLI alone does not replace a running guard or installed executable release. Fixed guest bootstrap refreshes the common workspace service in place. A receipt without launch proof keeps that start unconfirmed. Inspect the original operation; an unknown command result alone does not require restarting the companion or stopping its VM. For an incompatible control-contract edition, use the explicit maintenance interruption and confirm settlement. Before the coordinated cutover, back up the server database, the complete private companion state and SDK backing storage, including VM disks. Keep matching bundles, coordinate server/companion editions, then start the selected owner with the same state and disks. A coordinated rollback must preserve any writes made since the backup; do not restore an old database over new accepted work. Do not erase approval/journals, create replacement state or kill arbitrary guard processes. Management can be interrupted; mixed-edition rolling upgrade is unsupported. Live append in a matched edition does not make the upgrade itself uninterrupted.

For the management and addressed-resource read contracts, activate the matching controller producer through supported maintenance before switching the server reader. An unavailable management or addressed-resource route does not fall back to full native inventory. Check the active release and every VM’s recovery result; staging a bundle, server health or completed maintenance alone does not confirm that each VM recovered.

Archived cloud Local policy/control, relay, grants and operational rows remain diagnostic data; archives do not authorize dispatch. The owner imports only verified existing native bindings and retains unknown outcomes. An unsupported private owner format remains refused: preserve the cold backup, identity, journals and disks instead of editing cloud policy or deleting state. Rollback restores paired snapshots and matching bundles. Do not replace enrollment or reset the SDK.

An unknown command or file outcome belongs to its accepted operation; it does not itself require stopping or recovering the entire VM. Inspect its result and the affected files before repeating that effect or modifying those files. Independent work does not need to resolve that unknown outcome. Do not automatically replay an unknown edit or clear its journal to admit new work. For a runtime-owner refusal such as LOCAL_GUEST_SETTLEMENT_UNKNOWN, confirm physical stop before npm run local -- recover SPACE_ID --confirm. This checks exact native identity and the network boundary while preserving jobs and unknown outcomes without replay. With a running owner, first use the maintenance pause above, then resume that original maintenance ID and use run if needed. Use the same --state PATH. Ordinary stop/start requires no separate counter-recovery step. If the acknowledged unknown arose during initial preparation, recovery preserves its original operation and leaves setup incomplete. Repair the reported prerequisite, then explicitly resume-setup WORKSPACE_REF on the same known VM; do not treat acknowledgement as completed setup or permission for ordinary start. npm run local -- recover --confirm is the separate disabled-device orphan-shutdown acknowledgement. Neither deletes codespace data or authorizes adoption by SDK name. If shutdown remains pending or identity is unknown, retain the records and resolve that refusal before enabling more work. See local setup.

Recovery Scenarios

Scenario: Resume After Interruption

User: Continue working on the auth feature
Agent:
1. execution({ action: "executions", search: "auth" })
→ Found: executionId: "abc-123", status: "waiting"
2. execution({ action: "current_step", executionId: "abc-123" })
→ attemptId: "attempt-current", directive: "Implement login endpoint"
3. [Does the work]
4. execution({ action: "step", processId: "abc-123", attemptId: "attempt-current", input: { result: "done" } })

Scenario: Find Lost Process ID

User: What workflows am I running?
Agent:
1. execution({ action: "executions" })
→ Returns a page of active executions with notes
2. execution({ action: "execution_context", executionId: "abc-123" })
→ Shows full context including variables

Scenario: Check Why Workflow Stuck

Agent:
1. execution({ action: "execution_context", executionId: "abc-123" })
→ status: "waiting", currentNodeId: "validation-step"
2. execution({ action: "current_step", executionId: "abc-123" })
→ Shows what the workflow is waiting for