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
- 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" }]- 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": { ... }}- 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:
# Create process-id.txt in feature directoryecho "abc-123" > ./feature-name/process-id.txtInclude in session archives:
- Feature name
- Process ID
- Current step description
Navigation Tools Reference
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 workflowsearch: 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 presentationdirective: What to docompletionCondition: Success criteriainputSchema: 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 UUIDworkflowId: Workflow being executedstatus: Execution status (running, waiting, completed, failed)currentNodeId: Current node IDwaitingForInputNodeId: Node waiting for input (if any)taskTitle: Canonical task name, independent of the arbitrary notetaskIdentity: Persisted{ title, changedAt, changeId }ornullrevision,metadataRevisions.taskIdentity: Step and independent task-name revisionnote: Arbitrary execution notecontext.variables: Context variablescontext.nodeStates: Node execution statescreatedAt,updatedAt,completedAt: Timestampserror: 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:
- Use
execution({ action: "executions" })to find active executions - Use the correct executionId from the list
- Process IDs are UUIDs like
abc123-def456-...
“Execution is not waiting for input”
Cause: Trying to advance a completed or failed execution
Solution:
- Check execution status with
execution({ action: "execution_context", executionId: "..." }) - Inspect the actual waiting node and current presentation; a persisted
runningexecution can be waiting for input. Do not infer readiness from a display status alone. - 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:
- Check
inputSchemafrom current step - Verify field names match exactly (case sensitive)
- Verify data types match (string vs number)
- 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:
- Check for process-id.txt in workspace
- Use
execution({ action: "current_step", executionId })with the retained identity to get context - 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:
- The variable is not declared in
variableRegistry. - The variable is declared but has no
defaultand was not yet written by an upstream node before the directive used it. - 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:
- Use a declared global or the actual node-local path; seed a meaningful default only when the contract has one.
- Ensure the producing node runs before use; guard optional text instead of manufacturing evidence.
- 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:
npm run local -- maintenance --pause --confirmnpm run local -- collect ORIGINAL_MAINTENANCE_ID# Continue only after this original reports paused.npm run local -- loginnpm run local -- maintenance --resume --request-id ORIGINAL_MAINTENANCE_ID --confirmnpm run local -- runnpm run local -- service-statusKeep 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:
npm run local -- maintenance --pause --confirmnpm run local -- collect ORIGINAL_MAINTENANCE_IDnpm run local -- web-control --confirm --storage-gib 50npm run local -- maintenance --resume --request-id ORIGINAL_MAINTENANCE_ID --confirmnpm run local -- runUse 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 variablesScenario: 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 forRelated Documentation
- MCP Agent Guide - Tool usage basics
- MCP Tools Reference - Full tool documentation