Run shell blocks in `xmd` workflows

[taras]

Story

As a workflow author, I want executable shell blocks to run through the retained Workspace, so a repeatable workflow can use a constrained interpreted shell without gaining native process or host-filesystem authority.

Product contract

Under xmd workflow, the host installs a Workspace-scoped implementation of the existing contextual runtime.process API. Supported shell execution runs through Cloudflare's Workspace Shell model:

durable exec expansion
 → stable effect identity
 → one serialized Workspace effect transaction
 → Deno Worker
 → just-bash
 → Cloudflare WorkspaceFsAdapter
 → authoritative DOFS connection

The provider preserves the existing process shape:

{
 exitCode: number;
 stdout: string | undefined;
 stderr: string | undefined;
}

Authored bash and sh blocks both reach the provider as exactly
["bash", "-c", source]. The request's cwd is an absolute logical Workspace
path. No host environment is inherited, and an explicit environment request is
refused. Every other command array fails before a Worker or transaction is
created. It never falls back to the host PATH, native execution, writable
materialization, FUSE, workerd or Containers.

The Worker forwards stdout and stderr progressively through the existing Stdio
operations. The provider honors retain when the contextual API is called
directly. The ordinary executable-block path asks the provider not to retain;
core's per-exec boundary owns capture, binding, display routing and workflow
retention exactly as it does for every other process provider. Ordinary
xmd run keeps its existing host-process behavior.

Worker Shell names the capability. just-bash is its initial interpreter, not a promise of native Bash, POSIX completeness or a permanent public engine choice.

Effect transaction

One shell invocation owns one effect identity, one immediate SQLite transaction and one shell_mutations savepoint. DOFS operations use nested savepoints inside the caller-owned transaction.

A process that reaches an exit status always produces a settled
ProcessOutcome. Exit zero releases shell_mutations; a nonzero status,
including an interpreter refusal represented by an exit status, rolls
shell_mutations back. Both append an already-filtered successful durable
result and commit. This preserves the existing distinction: a bound exec treats
nonzero as data, while core turns an unbound nonzero status into a checked
failure.

A timeout or Worker failure before a status settles rolls shell_mutations
back, appends one already-filtered failed durable result and commits. Replay
raises that recorded failure without starting a Worker.

Structural Effection cancellation is not a completed process result. It fences
new filesystem RPC, force-terminates the Worker immediately, and aborts the
outer transaction. It publishes no exec result; the workflow lifecycle records
interrupted or cancelled, and resume executes the effect again against
the pre-effect Workspace root. A host crash has the same transaction
visibility: SQLite recovery exposes neither filesystem mutations nor a result
event.

The journal security policy filters the result before it enters this transaction boundary. This issue does not create another filtering system.

Connection and concurrency boundary

One host-owned DOFS connection is authoritative for each workflow database. Workspace-local effect transactions execute serially on that connection. Production code does not keep a second long-lived DOFS reader whose negative resolve-cache entries can survive another connection's commit.

All filesystem RPCs carry the stable effect ID, a per-invocation token and a request identity. The router rejects requests for a missing, foreign, cancelled or completed effect and rejects stale or late messages from an earlier invocation.

Worker lifecycle

Cancellation first prevents new filesystem routing and then forcefully
terminates the Worker. There is no graceful-shutdown interval on cancellation:
all durable cleanup is host-owned, and a CPU-bound just-bash program may
never return control to the Worker runtime.

The current proof uses @effectionx/worker@0.5.4 plus a diagnostic
force-termination delta. Production waits for a released upstream
force-termination contract that can preempt a non-cooperative Worker. The open
upstream work is
thefrontside/effectionx#242.

This repository will not carry a pinned patch or fork to deliver #181. Until the
supported upstream contract is released and consumed, #363 is blocked and is
not an #181 delivery dependency. Silent patch drift or graceful-only teardown
remains unacceptable.

Isolation

The production provider preserves the #351 and #357 proof boundaries:

• no host PATH or native executable;
• no host filesystem access;
• no inherited host environment;
• no default network route;
• Workspace path authorization on every filesystem operation; and
• CPU-bound execution is preemptible without starving host cancellation.

Replay

A committed shell result restores from the journal without starting a Worker. A host interruption before commit leaves no result and reruns the effect against the pre-effect Workspace root under the same durable identity.

Acceptance

• The Deno workflow adapter installs the Worker Shell process provider; shared production modules contain no Deno, Cloudflare or runtime-detection logic.
• xmd run process behavior is unchanged.
• The exact ["bash", "-c", source] request preserves the existing process result contract; every other command form and every explicit environment request fails without host fallback.
• Stdout and stderr reach the existing Stdio operations progressively; core remains the authority for capture, binding, display routing and workflow retention.
• One invocation owns one effect transaction and mutation savepoint.
• Exit zero publishes filesystem mutations and its filtered settled outcome atomically.
• A settled nonzero status publishes no filesystem mutation and records an ordinary successful ProcessOutcome; bound and unbound blocks retain their existing semantics.
• Timeout or Worker failure before a settled status publishes no filesystem mutation and exactly one failed durable result.
• Structural cancellation fences Worker RPC, force-terminates immediately, publishes neither mutation nor exec result, and leaves lifecycle reporting to the workflow executor.
• A real process crash after a shell write but before result publication leaves neither mutation nor result after restart.
• One authoritative DOFS connection serves the workflow database and local effect transactions are serialized.
• Missing, foreign, completed, cancelled and stale Worker messages are fenced.
• CPU-bound shell code is forcefully terminated immediately when cancellation or a command timeout begins teardown.
• Replay of a committed result starts no Worker.
• Containment probes cover host path, native execution, environment, network and filesystem escape.
• Tests exercise the contextual API through the same executable-block path a workflow document uses.
• The production binary records the released upstream Worker and force-termination dependencies reproducibly; no repository patch or fork is accepted.
• architecture.md and specs/workflow-workspace-spec.md are corrected in the implementation PR to use these settled exit-status, failure and structural-cancellation semantics.

Intentionally excluded

• Worker JavaScript.
• Native subprocesses, writable FUSE, workerd and Containers.
• A new public shell component when the contextual process API already carries the operation.
• External-effect atomicity.
• Changes to ordinary xmd run.
• Another journal secret policy.

Evidence and dependencies

• Spike: host Cloudflare DOFS directly in Deno with SQLite and FUSE #349 / PR 🔬 Spike: host Cloudflare DOFS directly in Deno with SQLite (#349) #350 proves Deno-local SQLite and DOFS.
• Spike: run Cloudflare Worker Shell and Worker JavaScript natively in Deno #351 / PR 🔬 Spike: run Cloudflare Worker Shell and Worker JavaScript natively in Deno (#351) #353 proves contained Worker Shell execution in Deno.
• Spike: make Worker Shell effects transactional with the workflow journal #357 / PR 🔬 Spike: make Worker Shell effects transactional (#357) #362 proves the effect transaction, failure rollback, host-crash recovery, routing fences, replay and force-termination requirement.
• 📝 Specify retained workflow Workspaces #358 records the architecture and observable workflow contract.
• Quest: Resume workflows with their Workspace, repositories, and Agent state #218 owns the retained Workspace, lifecycle and transaction foundation this provider consumes.
• Deferred follow-up after ✨ Compose and certify the supervised adversarial implementation workflow #181; implementation waits for a released upstream force-termination contract.