workjig 0.1.0__tar.gz

workjig-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zbigniew Lukasiak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workjig-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+recursive-include docs *.md
+recursive-include adr *.md
+recursive-include adr/evidence/terminal-failures *.py *.json *.jsonl *.log
+recursive-include examples *.py *.md
+recursive-include tests *.py *.md
+include uv.lock

workjig-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: workjig
+Version: 0.1.0
+Summary: Run headless LLM coding harnesses as subprocess workers from Python workflows
+License: MIT License
+        
+        Copyright (c) 2026 Zbigniew Lukasiak
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Workjig
+
+A Python workflow runtime that orchestrates headless LLM harnesses.
+
+Run Claude Code, Codex and Pi as subprocess workers. You write the workflow
+in Python; Workjig handles launches, separate output
+paths, bounded execution and durable run records.
+
+## Why Workjig?
+
+**Use existing harnesses, not another model API integration.** Workjig delegates
+work to coding harnesses through their command-line interfaces, using their
+tools, configuration and authentication. An important motivation is letting
+people use Claude Code with an eligible Anthropic subscription rather than
+requiring separate API billing. Availability depends on the harness, account,
+provider terms and usage limits; Workjig does not supply or bypass access.
+
+**Keep the whole workflow in Python.** Branches, parallel work, checks and
+correction loops are ordinary Python, not a separate graph or workflow language.
+Unlike libraries centered on direct model API calls, Workjig treats the harness
+as the worker. [mdflow](https://github.com/johnlindquist/mdflow) is another
+harness-based approach: it turns Markdown prompts into executable CLI commands
+that can be composed through pipes. For Commonplace, where most of the system
+is already Python, keeping workflow control in Python lets us reuse its code
+and tests without introducing another way to express control flow.
+
+**Keep the runtime small and independent.** Workjig's primary purpose is to
+support [Commonplace](https://github.com/zby/commonplace) as the foundation of
+its workflow engine. A separate package gives agents a focused codebase and a
+clear execution contract. Commonplace drives priorities, but its domain rules
+stay outside the runtime. Workjig requires neither Commonplace nor Git.
+Initial platform: Linux, Python 3.11 or newer.
+
+### Compatibility
+
+Workjig is in early development. We do not maintain backward
+compatibility for the public API or persisted run-record format. Changes may
+require updating callers and starting fresh run directories; no migration of
+older records is promised.
+
+### Code-steered or agent-steered?
+
+Agent-led delegation is useful for exploratory work where the process changes
+as we learn; our [lightweight review workflow](instructions/lightweight-review.md)
+uses that approach. Workjig is for code-steered work: execution rules live in
+Python, completed calls can be reused after restart, and interruptions require
+explicit recovery. We are trying both, not claiming one is always better.
+
+In [Treadle](https://github.com/zby/treadle), code controlled the workflow but an
+agent carried prompts and answers between it and workers. Workjig launches
+harnesses directly to remove that transmission and coordination layer.
+
+The supporting research lives in the [Commonplace KB](https://zby.github.io/commonplace/),
+including notes on [orchestration design dimensions](https://github.com/zby/commonplace/blob/main/kb/notes/agent-orchestration-occupies-a-multi-dimensional-design-space.md)
+and [coordination guarantees versus channels](https://github.com/zby/commonplace/blob/main/kb/notes/agent-orchestration-needs-coordination-guarantees-not-just.md).
+These inform the design; they are not evidence of Workjig's tested behavior.
+Our [design rationale](docs/design-rationale.md) explains the local tradeoffs.
+
+## A call
+
+```python
+import sys
+from pathlib import Path
+
+from workjig import CommandWorker, Request, Run
+
+worker = CommandWorker(argv=(sys.executable, str(Path("worker.py").resolve()), "{prompt}"))
+request = Request(
+    call_id="summarize-v1",
+    task="Read the supplied source and write the requested summary file.",
+    inputs={"source.txt": "Material to summarize."},
+    required_outputs=("summary.txt",),
+    worker=worker,
+    timeout_seconds=60,
+)
+
+with Run(Path("run-records"), Path.cwd()) as run:
+    result = run.call(request)
+    if result.status == "delivered":
+        print(result.outputs["summary.txt"])
+    else:
+        print(result.status)
+```
+
+Supply your own `worker.py`: it receives a generated prompt with absolute input
+and output paths, reads the inputs and writes the named files. Standard output
+is execution evidence, not the file result. For real harnesses, use the
+`claude_worker`, `codex_worker` or `pi_worker` factories instead of a generic
+`CommandWorker`; see [usage and adapter configuration](docs/usage.md).
+The [ordinary-file example](examples/README.md) provides a runnable workflow
+with checks, corrections and resume.
+
+## Guarantees and boundaries
+
+- **Reuse:** reopening a run reuses committed results only when the stable call
+  identity and declared work match. Timeout, launch ceiling, and retry policy
+  are not part of work identity. Ambient environment changes are not detected
+  automatically.
+- **Bounded execution:** one launch by default; retries and larger allowances
+  are explicit. Launches are reserved durably, and restart does not refund them.
+  A caller may raise the total ceiling to continue eligible failed work; usage
+  stops require explicit approval of the particular stop.
+- **Explicit recovery:** unresolved launches block automatic work until you
+  establish that the old worker has stopped and acknowledge it.
+- **Delivery is not acceptance:** your workflow checks content and bounds
+  correction loops. Reused results still need those checks.
+- **Separate files are not a sandbox:** callers own permissions, credentials,
+  environment compatibility and recovery of external effects.
+
+## Documentation
+
+- [Usage and recovery](docs/usage.md) — adapters, retries, outcomes, parallel calls
+  and recovery procedures.
+- [Execution contract](docs/design.md) — guarantees and limits.
+- [Design rationale](docs/design-rationale.md) and [decision records](adr/README.md)
+  — reasons, alternatives and tradeoffs.
+- [Harness evidence](docs/harness-evidence.md) — tested adapters and versions,
+  distinguishing deterministic tests from actual model invocations.
+
+## Development
+
+Run from this package directory:
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+Normal tests use direct parser checks and deterministic subprocess workers;
+they do not call model APIs or require credentials. See [test organization](tests/README.md)
+for selective runs and GitHub CI. Real-harness probes remain
+[manual operations](docs/usage.md#examples-and-real-harness-probes), outside CI.
+Building creates local artifacts; publishing is a separate step.
+
+## License
+
+[MIT](LICENSE).

workjig-0.1.0/README.md

@@ -0,0 +1,140 @@
+# Workjig
+
+A Python workflow runtime that orchestrates headless LLM harnesses.
+
+Run Claude Code, Codex and Pi as subprocess workers. You write the workflow
+in Python; Workjig handles launches, separate output
+paths, bounded execution and durable run records.
+
+## Why Workjig?
+
+**Use existing harnesses, not another model API integration.** Workjig delegates
+work to coding harnesses through their command-line interfaces, using their
+tools, configuration and authentication. An important motivation is letting
+people use Claude Code with an eligible Anthropic subscription rather than
+requiring separate API billing. Availability depends on the harness, account,
+provider terms and usage limits; Workjig does not supply or bypass access.
+
+**Keep the whole workflow in Python.** Branches, parallel work, checks and
+correction loops are ordinary Python, not a separate graph or workflow language.
+Unlike libraries centered on direct model API calls, Workjig treats the harness
+as the worker. [mdflow](https://github.com/johnlindquist/mdflow) is another
+harness-based approach: it turns Markdown prompts into executable CLI commands
+that can be composed through pipes. For Commonplace, where most of the system
+is already Python, keeping workflow control in Python lets us reuse its code
+and tests without introducing another way to express control flow.
+
+**Keep the runtime small and independent.** Workjig's primary purpose is to
+support [Commonplace](https://github.com/zby/commonplace) as the foundation of
+its workflow engine. A separate package gives agents a focused codebase and a
+clear execution contract. Commonplace drives priorities, but its domain rules
+stay outside the runtime. Workjig requires neither Commonplace nor Git.
+Initial platform: Linux, Python 3.11 or newer.
+
+### Compatibility
+
+Workjig is in early development. We do not maintain backward
+compatibility for the public API or persisted run-record format. Changes may
+require updating callers and starting fresh run directories; no migration of
+older records is promised.
+
+### Code-steered or agent-steered?
+
+Agent-led delegation is useful for exploratory work where the process changes
+as we learn; our [lightweight review workflow](instructions/lightweight-review.md)
+uses that approach. Workjig is for code-steered work: execution rules live in
+Python, completed calls can be reused after restart, and interruptions require
+explicit recovery. We are trying both, not claiming one is always better.
+
+In [Treadle](https://github.com/zby/treadle), code controlled the workflow but an
+agent carried prompts and answers between it and workers. Workjig launches
+harnesses directly to remove that transmission and coordination layer.
+
+The supporting research lives in the [Commonplace KB](https://zby.github.io/commonplace/),
+including notes on [orchestration design dimensions](https://github.com/zby/commonplace/blob/main/kb/notes/agent-orchestration-occupies-a-multi-dimensional-design-space.md)
+and [coordination guarantees versus channels](https://github.com/zby/commonplace/blob/main/kb/notes/agent-orchestration-needs-coordination-guarantees-not-just.md).
+These inform the design; they are not evidence of Workjig's tested behavior.
+Our [design rationale](docs/design-rationale.md) explains the local tradeoffs.
+
+## A call
+
+```python
+import sys
+from pathlib import Path
+
+from workjig import CommandWorker, Request, Run
+
+worker = CommandWorker(argv=(sys.executable, str(Path("worker.py").resolve()), "{prompt}"))
+request = Request(
+    call_id="summarize-v1",
+    task="Read the supplied source and write the requested summary file.",
+    inputs={"source.txt": "Material to summarize."},
+    required_outputs=("summary.txt",),
+    worker=worker,
+    timeout_seconds=60,
+)
+
+with Run(Path("run-records"), Path.cwd()) as run:
+    result = run.call(request)
+    if result.status == "delivered":
+        print(result.outputs["summary.txt"])
+    else:
+        print(result.status)
+```
+
+Supply your own `worker.py`: it receives a generated prompt with absolute input
+and output paths, reads the inputs and writes the named files. Standard output
+is execution evidence, not the file result. For real harnesses, use the
+`claude_worker`, `codex_worker` or `pi_worker` factories instead of a generic
+`CommandWorker`; see [usage and adapter configuration](docs/usage.md).
+The [ordinary-file example](examples/README.md) provides a runnable workflow
+with checks, corrections and resume.
+
+## Guarantees and boundaries
+
+- **Reuse:** reopening a run reuses committed results only when the stable call
+  identity and declared work match. Timeout, launch ceiling, and retry policy
+  are not part of work identity. Ambient environment changes are not detected
+  automatically.
+- **Bounded execution:** one launch by default; retries and larger allowances
+  are explicit. Launches are reserved durably, and restart does not refund them.
+  A caller may raise the total ceiling to continue eligible failed work; usage
+  stops require explicit approval of the particular stop.
+- **Explicit recovery:** unresolved launches block automatic work until you
+  establish that the old worker has stopped and acknowledge it.
+- **Delivery is not acceptance:** your workflow checks content and bounds
+  correction loops. Reused results still need those checks.
+- **Separate files are not a sandbox:** callers own permissions, credentials,
+  environment compatibility and recovery of external effects.
+
+## Documentation
+
+- [Usage and recovery](docs/usage.md) — adapters, retries, outcomes, parallel calls
+  and recovery procedures.
+- [Execution contract](docs/design.md) — guarantees and limits.
+- [Design rationale](docs/design-rationale.md) and [decision records](adr/README.md)
+  — reasons, alternatives and tradeoffs.
+- [Harness evidence](docs/harness-evidence.md) — tested adapters and versions,
+  distinguishing deterministic tests from actual model invocations.
+
+## Development
+
+Run from this package directory:
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+Normal tests use direct parser checks and deterministic subprocess workers;
+they do not call model APIs or require credentials. See [test organization](tests/README.md)
+for selective runs and GitHub CI. Real-harness probes remain
+[manual operations](docs/usage.md#examples-and-real-harness-probes), outside CI.
+Building creates local artifacts; publishing is a separate step.
+
+## License
+
+[MIT](LICENSE).

workjig-0.1.0/adr/001-name-physical-launch-records.md

@@ -0,0 +1,58 @@
+# 001 — Name physical launch records explicitly
+
+Status: accepted
+Decision date: 2026-10-20
+Recorded: 2026-10-20
+
+## Context
+
+Workjig records each physical launch reservation, including reservations for
+which no process started. Commonplace uses “attempt” for a larger unit of work
+that includes content checking and correction. Using the same word at both
+levels obscures which lifecycle and budget a caller is discussing.
+Commonplace's integration review identified this problem.
+
+## Decision
+
+Expose `LaunchRecord` and `CallResult.launches` in the Python API. Callers use
+these names when inspecting execution evidence and spent launch reservations.
+They align with `launch_id`, `launch_dir`, `max_launches`, and
+`unresolved_launches()`.
+
+Keep the version-1 persisted JSON field `attempts`. The public vocabulary change
+does not require a storage migration. This records the implemented choice
+retrospectively.
+
+## Considered alternatives
+
+**Keep `Attempt` and `CallResult.attempts`.** “Attempt” can reasonably include an
+effort to start a process. However, the consumer's different meaning creates
+avoidable ambiguity at the integration boundary.
+
+**Use `result.launch_records`.** This is explicit but unnecessarily repeats the
+record representation. `result.launches` reads naturally and matches the other
+launch-oriented API names.
+
+**Rename stored fields too.** Consistent spelling across Python and JSON would
+be tidier, but would introduce migration work unrelated to the consumer-facing
+problem. Existing records should remain readable without rewriting them.
+
+## Consequences
+
+The runtime and consumer can describe physical launches and workflow attempts
+without conflating their budgets. `LaunchRecord` also accommodates a reservation
+that never reached process start.
+
+Python consumers must use the new names; no compatibility aliases were added.
+Persisted records retain their format and existing execution/recovery behavior.
+Internal storage helpers can continue to use the old field terminology.
+
+The rename was checked by the functional suite and a separate verification
+session that compared old and new codecs across all 11 lifecycle statuses.
+This supports storage compatibility; it does not establish new harness behavior.
+
+## Reevaluate when
+
+Consumer integration reveals another concrete ambiguity in the launch lifecycle.
+Revisit the stored field name only if a separately justified record-format change
+makes migration worthwhile.

workjig-0.1.0/adr/002-classify-terminal-harness-failures.md

@@ -0,0 +1,88 @@
+# 002 — Classify terminal harness failures, not whole logs
+
+Status: accepted
+Decision date: 2026-10-20
+Recorded: 2026-10-20
+
+## Context
+
+The original `usage limit` scan could mistake quoted task content for a quota
+stop and suppress a configured retry. It also missed every quota failure in
+our local fixtures. Pi can report an assistant failure while exiting zero, and
+all three harnesses can recover after an intermediate error.
+
+[Protocol inspection](evidence/terminal-failures/README.md) and
+[15 real-CLI fixture probes](evidence/terminal-failures/local-probes.md) establish
+these distinctions for Codex 0.162.1, Claude Code 2.1.303 and Pi 1.3.0. The probes
+used isolated loopback providers, not live quota exhaustion. Subscription OAuth
+and other Pi provider transports remain outside the observed evidence.
+
+## Decision
+
+Select the final harness outcome first, then classify its cause. Adapter
+factories declare `CommandWorker.output_protocol`; worker names remain
+labels. Generic commands default to no stream interpretation. Protocol selection
+belongs to declared request identity, with the absent default preserving the
+canonical material of existing records. Committed outcomes are not reinterpreted.
+
+| Protocol | Terminal selection | Usage-stop signals |
+|---|---|---|
+| `codex-json` | Last `turn.completed` or `turn.failed` in the current turn | Known text in `turn.failed.error.message` |
+| `claude-stream-json` | Main-agent `result`; `subtype: success` still requires `is_error: false` | On an error result of that variant: last main-agent assistant `rate_limit`/`billing_error`, final HTTP 429, or known terminal error text |
+| `pi-json` | Last completed assistant message, read through non-aborted `agent_settled`; `stopReason: stop` succeeds | Known text in the final assistant's `errorMessage` when `stopReason: error` |
+
+Text matching is limited to selected error fields: usage-limit and quota-exceeded
+phrases, `insufficient_quota`, rate-limit wording/codes, credit-balance failure
+wording and terminal HTTP 429 forms. Ordinary messages, tool errors, retry
+notifications and stderr do not establish quota failure. Descriptive
+`parse_evidence` remains separate from outcome classification.
+
+Recognized quota, billing and **unrecovered transient rate limits** become
+nonretryable `usage_limit`. Harnesses already handle short retries; after they
+give up, workflow code decides whether and when to resume. Workjig does not add
+a second implicit backoff loop. Worker-written `usage_limit` problems remain
+independent explicit stop signals, not claims of verified provider exhaustion.
+
+Handled timeout wins. Either usage-stop signal wins over other completed-process
+failures, including lingering children, after process-group cleanup. Otherwise,
+existing cleanup and worker-problem precedence remains. Other terminal failures
+and missing or malformed completion evidence become `process_error`; a caller
+may explicitly retry that outcome within the launch allowance. A successful
+terminal event does not override a nonzero exit or certify delivered content:
+file collection and workflow checks still apply.
+
+## Considered alternatives
+
+- **Keep whole-log matching, or scan only stderr:** both retain quotation false
+  positives; stderr-only also misses the observed stdout failure channels.
+- **Use exit status alone:** sufficient for generic commands, but would accept
+  Pi's exit-zero errors if required files were already present.
+- **Treat any error event as terminal:** would stop successfully recovered runs.
+- **Automatically retry exhausted throttling:** duplicates harness retry policy
+  and can spend launches while an account or provider remains blocked. Keep the
+  resume decision in the workflow instead.
+- **Stop on every unknown harness failure:** would suppress intentional bounded
+  retries of ordinary process failures. Unknown failures use `process_error`.
+
+## Consequences
+
+The small version-scoped parsers cover retained failure/recovery streams without
+requiring harness installations in the normal tests. They are not universal
+provider-error classifiers. Unknown quota wording can still become a retryable
+`process_error`; missing completion cannot become delivery merely because the
+process exited zero. Authentication and local harness budget failures also use
+that generic outcome rather than new runtime statuses.
+
+Subscription limit notifications and Pi retry summaries are not independently
+used as quota evidence. The supported final outcome must establish the stop.
+Raw streams remain available for diagnosis; adding new protocol signals needs
+evidence rather than broadening a whole-log keyword list.
+
+## Reevaluate when
+
+- A supported CLI changes terminal framing, or retained real failures show a
+  different final-message sequence or quota representation.
+- Subscription OAuth or another provider transport needs a reliably classified
+  stop that these signals miss.
+- Actual workflows show that delegating exhausted throttling to callers is
+  impractical, with evidence for a bounded runtime scheduling policy.

workjig-0.1.0/adr/003-separate-execution-controls-from-work-identity.md

@@ -0,0 +1,101 @@
+# 003 — Separate execution controls from work identity
+
+Status: accepted
+Decision date: 2026-10-20
+Recorded: 2026-10-20
+
+## Context
+
+Commonplace needs to increase timeouts without relaunching delivered work, extend
+failed calls' launch ceilings, and explicitly continue after resolving usage
+limits. Previously, timeout, ceiling, and retry policy were part of request
+identity. Changing any of them created a separate history and fresh allowance,
+rather than continuing the existing work.
+
+The [review proposal](evidence/execution-policy-and-continuation-proposal.md)
+explored these changes. The maintainer confirmed there are no saved runs to
+preserve, backward compatibility is not required, and run migration across code
+changes is out of scope. Resume supports recovery with compatible workflow and
+runtime code and environment, not upgrades across incompatible changes; changing
+execution controls is compatible by design.
+
+## Decision
+
+Exclude `timeout_seconds`, `max_launches`, and `retry` from work identity. Keep
+all other declared material identity-bearing. Matching delivered results replay
+under changed execution controls, with workflow checks still caller-owned.
+`CallResult.request_hash` now hashes work material, not execution controls.
+
+Evaluate the current call's controls against its existing history. The ceiling
+is total reservations, not additional launches: increasing two to three permits
+one further launch after two were spent. Retry eligibility and backoff are
+independent of the ceiling. Increasing timeout alone authorizes no retry. Lower
+ceilings stop further work when reached but do not invalidate historical counts.
+`failed_at_launch_limit` uses the currently supplied ceiling.
+
+Persist effective timeout, ceiling, and retry policy with every reservation
+before process start. Validate each launch against its recorded ceiling and
+continuation permission rather than the controls supplied today.
+
+Keep usage stops outside ordinary retry policy. `Run.call(request,
+resume_usage_stop=launch_id)` explicitly approves the named usage stop in that
+exact history. Approval overrides only the latest stop, while allowance remains.
+The next reservation records `resumed_usage_stop`; once reserved, the approved
+stop is no longer latest. Repeating approval after continuation or delivery is
+harmless. A new usage stop requires new approval. Other subsequent failures
+follow ordinary bounded retry policy. Current backoff also applies before an
+approved continuation. Invalid, unknown, wrong-entry, and non-usage references
+raise `ValueError` once unresolved-launch recovery permits inspecting the call.
+
+Unresolved reservations still require establishing worker termination and
+explicit acknowledgment. No allowance is refunded and no unrecorded output is
+adopted. Fresh launch paths, process cleanup, and parallel settlement are
+unchanged. `protocol_error` remains nonretryable.
+
+Use record format version 2 and reject older formats. Do not provide migration
+or a legacy mode. Keep the stored `attempts` field name; renaming it is unrelated
+to this change. ADR 001's historical format-preservation rationale does not imply
+a continuing compatibility commitment. Always store `output_protocol`, including
+an absent value; ADR 002's omission of that default to preserve existing records
+no longer applies.
+
+## Considered alternatives
+
+- **Keep execution controls in identity:** avoids changing the record contract,
+  but cannot preserve delivered work while updating controls and gives policy
+  variants separate budgets. Rejected for Commonplace's use case.
+- **Reset the budget or treat an increased ceiling as extra launches:** could
+  replenish allowance on repeated calls or restart. Rejected; spent reservations
+  always count against the supplied total.
+- **Separate durable budget grants or pending approval ledger:** adds state and
+  crash/replay accounting. Unnecessary: the supplied total ceiling plus durable
+  reservations tracks budget, and the next reservation records stop approval.
+- **Let a longer timeout imply retry permission:** conflates execution settings
+  with authorization. Require explicit ceiling and eligible retry outcome.
+- **Permanent usage-resume boolean or `usage_limit` in retry policy:** could
+  relaunch repeatedly while usage remains blocked. Bind permission to one stop.
+- **Exactly one launch after approval, even for other retryable failures:** adds
+  special retry semantics. Clear only the named usage stop, then use ordinary
+  bounded retries; any later usage stop blocks again.
+- **Separate continuation operation:** not needed for current callers. Use
+  per-call controls and one stop-ID argument rather than a second lifecycle API.
+- **Legacy mode or merging policy-variant histories:** adds unsupported migration
+  work and ambiguous result/budget selection. No saved runs require it.
+
+## Consequences
+
+Execution authorization can evolve without discarding delivered answers or
+launch evidence. Changing work material still creates a separate history.
+An answer delivered under old controls is not a promise about the hypothetical
+answer under new controls; callers wanting new work choose a new identity/run.
+External effects can repeat, and their recovery remains caller-owned.
+
+The record format and public hash meaning change without compatibility shims.
+Supporting [evidence](evidence/execution-controls/README.md) records deterministic
+checks, independent verification, and pre/post source-size measurements. These
+checks do not establish new real-harness support claims.
+
+## Reevaluate when
+
+Commonplace demonstrates a need not covered by per-call controls and stop-ID
+approval, or deterministic recovery tests reveal ambiguous authorization.