START HERE

What you will learn

  • Explain why a process wrapper is not an autonomous execution platform.
  • Design for timeouts, retries, queue leases and duplicate deliveries.
  • Separate candidate generation from trusted validation and publication.

Before you start: Familiarity with repositories, test commands and containers. The command example is illustrative and must be checked against the pinned tool version in your own worker image.

Reference edition: Provider-neutral reference design; named tools are implementation examples. Sources checked 2026-11-12.

Prepare a disposable workspace

Start each run from an approved repository and exact base commit. Pin the worker image, execution-engine version and dependency lockfiles. Install dependencies in a controlled preparation stage, then give the execution stage only the access it needs. Use synthetic fixtures and a disposable database, never a copy of raw customer data as a convenient default.

A container is one layer of isolation, not an automatic security guarantee. Run without unnecessary privileges, avoid host filesystem and Docker-socket mounts, constrain egress, and set CPU, memory, disk and runtime limits. Repository setup scripts and tests can execute arbitrary code, so their credentials and network access deserve the same scrutiny as the coding engine.

Keep unattended execution inside pre-approved boundaries

Use the engine’s supported non-interactive interface and consume structured events where available. Pin an adapter profile rather than assembling arguments from untrusted ticket text. With Codex, the documented entry point is codex exec; workspace-write allows scoped edits. The older --full-auto flag is no longer supported in the documentation checked for this guide.

The example below does not grant unrestricted execution or guarantee every operation can proceed. If the environment cannot perform an authorised dependency or test step within policy, record a clear failure or block. Do not remove the sandbox to avoid an operational question. Model-provider credentials should be mediated or scoped to the execution stage; do not expose a general credential bundle to repository-controlled scripts.

Stream events and supervise the whole process tree

A small Node.js wrapper can spawn an executable without a shell and read its stdout and stderr. A real supervisor also needs bounded log storage, event-size limits, structured parsing, redaction, cancellation and a wall-clock deadline. Do not collect an unlimited output string or pass process.env wholesale into an untrusted workspace.

An abort signal or child-process kill is not proof that every descendant process stopped. The outer container or job supervisor must terminate the task’s process group or runtime, escalate after a grace period, verify shutdown and remove temporary credentials and workspaces. Retain only redacted artifacts under a defined access and retention policy.

Assume a queue message can arrive twice

A durable queue schedules work; it is not the authoritative task database. Standard queues such as Amazon SQS can redeliver a message. Claim the execution with an atomic state update and unique task-attempt identity before running it. Record ownership and a fencing token so an old worker cannot publish after its lease has been superseded.

Renew the queue visibility timeout while a healthy run is active, but do not treat renewal as an exclusive lock. Persist the terminal outcome and required follow-up events before acknowledging the message. If a worker crashes after publishing a change request but before acknowledgement, recovery should reconcile the existing branch and change request instead of publishing another one. Use a dead-letter path for repeated delivery failures and an explicit operator recovery process.

Validate a revision, not a persuasive explanation

Run repository-appropriate checks: backend tests and static analysis, frontend linting and tests, and integration checks where they are relevant. The trusted validation profile comes from outside the candidate change. Inspect modifications to test and CI configuration so the worker cannot pass by weakening the gate. Record exact commands, exit codes, artifacts and the commit or content digest they checked.

Fresh independent CI checks the submitted revision again. It should use isolated fixtures, constrained permissions and protected workflow policy. Required checks and review rules must apply to the commit actually accepted; independent execution alone cannot establish independence if the candidate can rewrite every check.

Bound remediation and separate publication

A validation failure becomes a narrowly scoped repair task containing the failed check, a redacted diagnostic and the original contract. Allow a fixed budget, such as two repair attempts, then end with a clear failure or block. Keep infrastructure outages distinct from code failures: rerunning a missing network dependency through the model rarely fixes the cause.

After local checks pass, a trusted publisher uses a separate identity to push the approved revision and open a change request. The coding sandbox does not need a token that can merge or deploy. Report Review to the task source, wait for independent CI and acceptance, and maintain a cancellation route throughout.

Technical examples

One execution-engine adapter example: Codex CLI

Verified against the official non-interactive documentation on 12 November 2026. This invocation is one adapter example, not the complete worker. Pin and test the CLI and its policy configuration. The control service still owns limits, credentials, validation, publication and state.

codex exec \
  --sandbox workspace-write \
  --json \
  "Implement only the approved task in TASK.md; report any blocked action."

Illustrative Node.js process boundary

Schematic code, not a drop-in production runner. The trusted adapter supplies arguments; ticket text cannot choose an executable or directory. The sinks must handle streaming, backpressure, limits and redaction. A runtime supervisor enforces deadlines and process-tree termination. A zero exit code is not permission to mark the task completed.

import { spawn } from "node:child_process";

// All values below are resolved by trusted worker configuration.
const child = spawn(engineProfile.executable, engineProfile.arguments, {
  cwd: approvedWorkspace,
  shell: false,
  env: scopedExecutionEnvironment,
  stdio: ["ignore", "pipe", "pipe"],
  signal: cancellationSignal
});

child.stdout.on("data", boundedEventSink.write);
child.stderr.on("data", boundedDiagnosticSink.write);
child.on("error", recordInvocationFailure);
child.on("close", recordProcessOutcome);

Step-by-step process

  1. Build a known worker image

    Include required language runtimes, package managers, the pinned coding engine and project test tools. Verify startup without a personal interactive profile.

  2. Acquire work with durable ownership

    Resolve the contract, atomically claim the attempt, start a lease and create a disposable checkout. Reject duplicate or stale ownership before making changes.

  3. Execute with a deadline

    Stream bounded, redacted events, watch health and cancellation, and keep the runtime and cost budget visible.

  4. Validate and repair within limits

    Check the candidate against the trusted profile. Give specific failures to a bounded repair run; stop when limits are reached.

  5. Publish and reconcile

    Use a separate publisher, record the change-request ID and exact revision, persist follow-up status events and acknowledge the queue delivery.

FOLLOW ONE EXAMPLE

Worked scenario

The worker dies after opening a change request

A worker successfully validates a postcode fix. The publisher opens a change request, but the process fails before the queue message is acknowledged.

  1. The queue redelivers the message. The control service finds the existing attempt and change-request reference rather than treating it as new work.
  2. Recovery verifies the branch revision and publication record. If publication is uncertain, it searches using the stable task/attempt reference before taking another action.
  3. The service records the Review transition and retries the pending project-tool update. It does not re-run implementation or open a duplicate proposal.
  4. If the previous worker is still alive, its old fencing token prevents another publication after ownership has changed.

What this shows: The failure becomes a reconciliation problem with recorded evidence, rather than two competing code changes. Queue delivery and business completion are separate concerns.

The process at a glance

A worker claims durable ownership before execution. Passing validation permits publication, while lease checks, bounded repair and reconciliation protect retries from creating duplicate work.
ProcessDecisionHuman checkpoint
Read Mermaid diagram source
flowchart TD
 Q[Queue delivery] --> L{Claim valid lease}
 L -->|No| D[Reconcile or defer duplicate]
 L -->|Yes| W[Prepare isolated workspace]
 W --> E[Run bounded coding engine]
 E --> V[Trusted validation]
 V --> P{Checks pass}
 P -->|No and budget remains| R[Repair within original scope]
 R --> E
 P -->|No and limit reached| F[Persist failure and clean up]
 P -->|Yes| U[Trusted publisher]
 U --> S[Persist review and pending updates]
 S --> A[Acknowledge delivery]
 A --> C[Independent CI and acceptance]

What you should have at the end

  • A supervisor design covering workspace, process, credential and queue failures.
  • An evidence trail linking validation and publication to one exact candidate revision.

Common mistakes and how to avoid them

Returning success because the subprocess exited zero

Check product acceptance evidence and trusted test results. Treat the engine result as one input.

Retrying every failure through the model

Classify infrastructure failures separately and cap remediation. Repeated model calls can add cost without addressing the cause.

Giving tests the deployment environment

Dependency hooks and tests are executable code. Keep production credentials and unrestricted publisher tokens out of their environment.

Using queue visibility as the only lock

Use durable ownership, stale-worker protection and idempotent external effects in addition to queue timing.

APPLY THE IDEA

Try it yourself

Your task: Design a recovery drill in which your worker stops immediately after publication but before queue acknowledgement.

What to produce: A sequence of durable records and reconciliation steps showing why the retry creates no second change request.

Check your understanding: Can an expired worker still publish, and how does the platform prove it has stopped before reassigning work?

Key terms in plain English

Lease
Temporary recorded ownership that must be renewed while work continues.
Fencing token
A monotonically changing ownership value checked before an external effect is accepted.
Visibility timeout
A queue interval during which a received message is hidden from other consumers.
Bounded remediation
A limited repair attempt that retains the original scope and budget.

Sources and further reading