Producers — agent reference

Turns one validated producer request into at most one provider exchange and returns an untrusted Repository Proposal for repository.seal, or an explicit non-success. Two transports implement the one contract: the Claude Code CLI (ClaudeProducer) and the OpenAI Responses API (OpenAiProducer). A producer never applies, writes, integrates, verdicts or grants anything.

Status: Accepted: provider-neutral producer contract, Claude CLI and OpenAI Responses adapters under independent review (Astra round 9 PASS, 2026-09-28). Live transports unavailable: Claude (rules revision 5 needs re-qualification; 5 built-in agents + 2 plugins lack established inert meaning), OpenAI (no Platform credential). Nothing composes it yet. Report: <local evidence archive>. It accepts the scoped implementation, not live transport qualification: Astra ran 128/128 read-only tests and 32 in-memory probes, its sandbox blocked the filesystem, process and HTTP tests, and the 397/397 focused offline tests are the local run. Rounds 1–8 (impl-verify-r1.md–r8.md) returned FAIL; each round confirmed the previous round's fixes, and round 9 confirmed round 8's (observation-only group checks after reaping; consistent review status) and the revision-5 rules. After round 9, the post-reap group check and the qualification control settlement observe through a transient EPERM instead of reporting unknown at once (a load-sensitive test exposed it); that change has regression tests and is not yet independently reviewed. The live Claude qualification of 2026-09-28 decided unavailable, and no commission exists (Claude receipt). The qualification receipt is for rules revision 4; the current rules revision 5 requires re-qualification. That receipt stays byte-unchanged as the record of the revision-4 run (policy digest sha256:4685bfc7…5246); the rule changes made in review since then (deadline classification, remote evidence, observation-only cleanup after reaping) are revision 5, and a commission binding the revision-4 digest is refused as qualification-mismatch. The OpenAI transport is unavailable no-platform-credential, with no live request (OpenAI receipt). The OpenAI receipt is for rules revision 4; revision 5 requires re-qualification when a Platform credential exists. That receipt stays byte-unchanged as the revision-4 record (policy digest sha256:31243da3…115d); the review changes to its remote and deadline rules are revision 5, and a commission binding the revision-4 digest is refused as qualification-mismatch with nothing sent. This is local development only, and all 27 epics remain open. Long-form contract: local development.

• Source: src/producer.ts (the provider-neutral contract), src/claude-producer.ts, src/openai-producer.ts; qualification: scripts/qualify-claude-producer.ts
• Tests: test/producer.test.ts, test/producer-adversarial.test.ts, test/claude-producer.test.ts, test/claude-producer-boundaries.test.ts, test/claude-producer-seam.test.ts, test/openai-producer.test.ts, test/openai-producer-boundaries.test.ts, test/qualify-claude-producer.test.ts
• Helpers: test/helpers/producer.ts, test/helpers/claude-harness.ts, test/helpers/claude-events.ts, test/helpers/fake-claude-cli.mjs, test/helpers/fake-openai.ts

Intelligence: required — producer/propose via frontier/high

What it hides

• Provider mechanics. The pinned CLI's argv, environment, cwd, stdio, stream-json protocol, process group, kill and cleanup. The Responses API body, headers, fetch options and response shape. Callers see one request type and one result type.
• Admission timing. All preparation happens first (validation, prompt, pin hash, managed-policy read, call directory). The gate's admit is then the last asynchronous step before the spawn or send, and record runs exactly once afterwards.
• Wire format and mapping. The model returns {"edits":[{"path","baseSha256","content"}]}. parseProposalText maps it to FileEdit {path, prior: "sha256:" + baseSha256 | null, text: content}, which is the trust boundary.
• Retention. Provider values reach receipts, consumption records, messages and sf:producer notifications only as fixed classifications, grammar-checked tokens (GRAMMARS), checked numbers, byte counts or digests. stderr and error bodies are counted and digested, never kept.
• Credentials. OpenAiCredential keeps its value in a module-private record. It never serialises, prints or inspects to the value, and only the send boundary reads it. The Claude transport holds no credential: the CLI uses the existing sign-in under the real HOME.

Public interface

Constants (src/producer.ts:31-103):

Contract (src/producer.ts)

• interface Producer { provider; model; capabilities: ProducerCapabilities; produce(request: ProducerRequest, signal?: AbortSignal): Promise<ProducerResult> }
• parseProducerRequest(value: unknown): ProducerRequest (:657): an exact, descriptor-based deep-frozen copy. The fields are protocol, product, slice {id, revision}, attempt {runId, epoch 1–20, attemptId = runId/epoch, owner}, base {commit, tree}, files: SourceFile[] (0..maxFiles, path order, sha256 and blob recomputed), scope (sorted), brief {digest, text}, provider, model, effort, allowance, bounds: ProducerBounds (all ten, nothing defaults), hardBounds (sorted, unique).
• requestManifest, requestDigest (:780, :800): the canonical request with each file reduced to {path, mode, blob, sha256, bytes}.
• parseProducerCommission, commissionDigest, parseManagedPolicy (:813-868). ProducerCommission {protocol, provider, model, policyDigest, managedPolicy, completenessAudit, processContainment: "none", disposition: "accepted-scoped", receipt {path, sha256}, date, auditor}.
• renderProducerPrompt(request): RenderedPrompt {text, bytes, digest} (:889) is deterministic: every file block is data delimited by its byte count. PROPOSAL_JSON_SCHEMA is the strict wire schema.
• parseProposalText(text, {files, scope, bounds}): {ok: true, proposal, digest, bytes} | {ok: false, reason: "malformed-proposal" | "rejected-proposal", message} (:956) is pure.
• interface DispatchGate { admit(dispatch: ProducerDispatch): Promise<Admission>; record(consumption: AllowanceConsumption): Promise<void> } is supplied by the caller (unbuilt: the accepted Product gate has no producer dispatch kind, and step-1 spec §7 D1 leaves this to step 2's composition). class GateRejection(code, message) is the only definite "no" from record.
• ProducerResult is {status: "proposal", proposal, digest, bytes, receipt, allowance} or {status: "unavailable" | "failed" | "interrupted", reason, message, receipt, allowance}. ProviderReceipt, AllowanceConsumption, LocalDisposition, ClaudeTransportRecord, OpenAiTransportRecord and InventoryRecord are exported types.
• class ProducerError { code: "invalid-input" | "invariant" }.
• Seam: unsafeQualificationRun({archive, sentinels?, canaries?}) binds exactly one producer instance.

Claude (src/claude-producer.ts)

• Pins (:94-201): CLAUDE_EXECUTABLE <home directory path>, CLAUDE_EXECUTABLE_SHA256 d8cb1e5c…d21e, CLAUDE_VERSION 2.1.283, CLAUDE_MODEL claude-opus-5-5, CLAUDE_PLATFORM darwin/arm64, CLAUDE_MANAGED_SOURCES, CLAUDE_PATH /usr/bin:/bin, CLAUDE_LANG en_US.UTF-8, CLAUDE_PROTOCOL_CAPABILITIES, CLAUDE_INERT_INVENTORY (empty tools, MCP servers, skills, slash and terminal commands, agents, plugins and memory paths; permissionMode: "dontAsk"; output_style: "default"), CLAUDE_INIT_KEYS, CLAUDE_ARGV_TEMPLATE, CLAUDE_TRANSPORT_POLICY (rules revision 5; the qualification receipt records revision 4), CLAUDE_POLICY_DIGEST, CLAUDE_CAPABILITIES.
• new ClaudeProducer({root, gate, commission}, pins?) (:285). root is a canonical 0700 directory of this user, outside any directory holding .git, .claude, CLAUDE.md, AGENTS.md or .mcp.json. commission is a parsed commission, null or a qualification run. pins is reachable only through unsafeClaudeTransportPins.
• checkClaudeExecutable(path, sha256, deadline?, signal?), observeManagedPolicy(sources, deadline?), claudeManagedSources(username).

OpenAI (src/openai-producer.ts)

• OPENAI_ENDPOINT https://api.openai.com/v1/responses, OPENAI_MODEL gpt-6-astra, OPENAI_EFFORTS low to xhigh (max is invalid input), OPENAI_REQUEST_KEYS, OPENAI_RESPONSE_KEYS, OPENAI_FETCH_OPTIONS, OPENAI_TRANSPORT_POLICY (rules revision 5; the receipt records revision 4), OPENAI_POLICY_DIGEST, OPENAI_CAPABILITIES.
• class OpenAiCredential (:165, fromValue(value)), describeOpenAiAvailability(env): {credentialPresent} (presence only), new OpenAiProducer({credential, gate, commission}, endpoint?) (:244), and buildOpenAiRequest(request, prompt, endpoint): {manifest, body} (:318, pure).
• Seams: unsafeTestCredential (sk-test- only), unsafeOpenAiEndpoint (http://127.0.0.1:<port>/ only) and unsafeOpenAiSendBoundary.

Invariants and guarantees

1. Commission first. Without a commission, every produce is unavailable not-commissioned before anything is spawned or sent. A commission whose provider, model, policy digest or managed-policy state differs is qualification-mismatch.
2. Hard bounds are declared. A hardBounds entry the transport only estimates or does not enforce is unavailable unenforceable-bound before contact. Claude does not enforce maxOutputTokens and only estimates maxCostCents. OpenAI has no spend bound.
3. At most one exchange. Each call makes one spawn or one HTTP request, with no retries of any kind. exchange.invocations is 0 or 1.
4. Admission is the last step before the effect. A denial, a throw, a malformed answer (read by descriptor, never through a getter) or no answer within gateMs is interrupted not-admitted, and nothing is sent. The wait is judged on the monotonic clock: an answer or throw that settles after gateMs (even after the gate blocked the event loop) is unanswered, never an admission, and an overdue record acknowledgement is unknown. A cancellation or expiry after admission sends nothing and keeps the admission recorded.
5. Record exactly once. record runs for every status. allowance.recorded is yes, no (a GateRejection only) or unknown, and it never changes the status.
6. remote is conservative. It is none when nothing was sent. It is completed only for a validated terminal response with exact model identity, or a definitive authentication rejection (OpenAI HTTP 401/403, Claude api_error_status 401/403). For Claude that means a result with valid numbers, subtype success, is_error: false, a string result, terminal_reason: "completed", a null api_error_status and modelUsage naming exactly the requested model and canonical model, from a process that exited on its own, was never stopped, closed its pipes before the deadline and wrote nothing after the result (this resolves spec §2.2 step 9's weaker required-key rule conservatively; a CLI error result is unknown). For OpenAI that means a response object with a resp_ id, the exact model and a structurally consistent terminal status: completed with null error and incomplete_details; incomplete with null error and a string reason; failed with an error object of text-or-null type/code/message and null incomplete_details. Everything else is unknown, including any stop after the CLI exited and any unfinished fragment.
7. Claude runs the pin only, in a narrowed configuration. Before every spawn it hashes the executable through an O_NOFOLLOW descriptor and reads the managed policy, which must equal the commission's. The argv is fixed (--tools "" --safe-mode --restricted --strict-mcp-config --setting-sources "" --settings '{}' … --permission-mode dontAsk --max-budget-usd, with no --bare, resume, fallback or --json-schema). The environment is exactly HOME, PATH, LANG and TMPDIR, with descriptors 0–2 only and its own process group.
8. Claude stream rules fail closed. The first event is system/init, and its key set, version, model, cwd and inventory must match. Then only thinking-token and rate-limit events, one assistant message without tool blocks, and one successful result equal to the assistant text. Any violation, overflow, deadline or cancellation kills the group at once while the process is unreaped; a reaped process is never signalled. The deadline is classified apart from that signal. It is checked on the monotonic clock whenever output, the exit or the pipes' close is delivered, and its timer expires any exchange not yet ended, even after the exit. Output, an exit or a close observed after the deadline (after the event loop was blocked, or after an exit observed in time) is interrupted deadline with remote: unknown, never a proposal, and overdue output is decided before any of it is read.
9. Claude cleanup. Only an unreaped process is ever signalled destructively: until it is reaped, its PID and group number cannot be reused. After reaping, the group is only observed with signal 0, repeated for up to CLAUDE_KILL_CONFIRM_MS until it answers ESRCH (empty); otherwise the last answer decides: success is alive, EPERM or another error unknown. EPERM is observed through, not final at once: a member still being torn down after the group SIGKILL answers EPERM for a few milliseconds before ESRCH (seen on macOS under CPU load). Signal 0 shows existence, not ownership, so a survivor and an unrelated group that reused the number are not told apart, and neither is signalled. The qualification script settles its discovery control the same way, and a present or unknown group blocks calls 1 and 2. The call directory is removed entry by entry only when the process was reaped, its pipes closed and its group was empty. Otherwise it is retained, with the reason in local.
10. OpenAI send boundary. It rebuilds and compares the body and the manifest byte for byte before reading the credential, and rechecks the deadline (on the monotonic clock) and cancellation immediately before fetch and again after the headers and every settled body read, the end of the body included; an overdue or cancelled exchange is stopped as interrupted with remote: unknown. It uses redirect: "error", caps the body, and never parses a body that contains the credential (provider-error). A production credential never goes to a test endpoint, and a test credential never leaves loopback.
11. A proposal is data. It is FileEdits in path order within scope, with correct priors, inside maxEdits and maxEditBytes and the repository's accounting and layout. Messages name edits by index, never by the provider's path.

Failure semantics

• produce throws only a ProducerError: invalid-input for the caller's own request (nothing contacted), or invariant for an adapter bug before any effect. Provider and gate behaviour never throws.
• An authentication failure before the CLI's init event is failed missing-init: stderr is never interpreted.
• usage.billed is always unknown. Claude's cost is the CLI's own estimate when a result arrives, and otherwise unknown. spent is none, unknown or reported, never an invented zero.
• A failed call does not license a retry. The caller must reconcile remote: unknown, a retained directory or a non-empty group before dispatching the same Attempt again.

Trust scope

Established locally (macOS arm64, Node 26.8.1, 399 offline tests (397 when round 9 reviewed them) with a fake CLI run by node and a loopback fake server; the receipts record the 344 that passed at qualification time):

• Exact request, commission and proposal validation, with every rule and its limits.
• Argv and request body asserted against literal copies of the contract.
• Admission ordering, cancellation and deadline races (including reads that settle after the deadline), overdue gate answers, and exactly-once recording.
• Stream, identity and inventory rules, stops, cleanup, process groups and the retention rule.
• Credential non-disclosure, including JSON-escaped echoes, and endpoint pairing.

Observed live once (2026-09-28, one spawn that may have reached the provider; call 2 not run): under the narrowed argv, the pinned 2.1.283 CLI emitted an init with version 2.1.283 and model claude-opus-5-5. Tools, MCP servers, skills, commands and memory paths were empty, but there were 5 agents and 2 plugins. The adapter failed closed (capability-inventory) and killed the group 188 ms after spawn, before any assistant or result event. The group was empty, the call directory removed, and sentinels, canary and both synthetic repositories unchanged. remote: unknown, and spend is unknown. The unrestricted discovery control exited with code 1 without an init, so it is not-established, although its SessionStart hook and MCP sentinel ran.

Composition

• Depends on: src/canonical-json.ts (Command journal) for canonical digests and strict reads; src/repository.ts (Repository) for the FileEdit, Proposal and SourceFile types and REPOSITORY_LIMITS, unchanged. Otherwise Node builtins only.
• Used by: nothing in src/ or apps/. The only importers are the tests and the qualification script.
• Intended caller contract: a composition root parses a person-committed ProducerCommission and supplies a durable DispatchGate (the Product aggregate's admitDispatch and the Slice allowance; unbuilt, see above). It passes a SourceSnapshot's selected files, then hands result.proposal to repository.seal, which re-decides everything.

Changing it safely

• Run (only when told):

  • focused: node --test test/producer.test.ts test/producer-adversarial.test.ts test/claude-producer.test.ts test/claude-producer-boundaries.test.ts test/claude-producer-seam.test.ts test/openai-producer.test.ts test/openai-producer-boundaries.test.ts test/qualify-claude-producer.test.ts;
  • npm run typecheck, and npm run check before acceptance.

  Never run scripts/qualify-claude-producer.ts without --openai-only unless a person has authorised the spend: it spawns the real CLI.

• Which tests prove what:

  • producer.test.ts (69): request, commission and proposal rules, digests, prompt, gate waits, consumption and receipt bounds.
  • producer-adversarial.test.ts (3): event-type confusion.
  • claude-producer.test.ts (132) and claude-producer-boundaries.test.ts (31): argv, environment, commission, managed policy, admission, stream, identity, remote evidence, stops, pins, cleanup, canaries and process groups.
  • claude-producer-seam.test.ts (16): seams, policy digests (including both revision-4 receipts as history) and credential pairing.
  • openai-producer.test.ts (89) and openai-producer-boundaries.test.ts (15): manifest, response rules, terminal consistency and remote, credential echo, statuses, deadlines, redirects and send-boundary tampering.
  • qualify-claude-producer.test.ts (44): the script's process, sequencing and decision rules with injected observations.

• Policy digests are commitments. Any reviewed change to argv, environment, init keys, inventory, events, the system prompt, managed sources or the stream, stop, deadline and cleanup rules (spec §2.3–§2.7 for Claude, §3.2–§3.5 for OpenAI) must bump rulesRevision. That changes CLAUDE_POLICY_DIGEST / OPENAI_POLICY_DIGEST, so an existing commission stops matching and the transport must be re-qualified. Widening CLAUDE_INERT_INVENTORY (for example, to admit the 5 agents and 2 plugins) needs a person's completeness audit with evidence of inert meaning, then re-qualification.

• Receipts are written by the script, never by hand. A commission is written only for accepted-scoped, and committing it is the person's act.

• Reviewers check: no new argv, environment entry or descriptor; admission is still the last asynchronous step; there are still no retries; unknown is never downgraded; no provider text is retained; and no production path calls an unsafe* seam.