claude-dev-env 8.26.6 → 8.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,62 +1,31 @@
1
1
  # Executor consult block
2
2
 
3
- Paste parts for every executor spawn ticket this skill issues.
4
- Assemble at ticket write time. Paste the assembled text at the **top**
5
- of the spawn prompt.
3
+ Use this text in a scoped executor brief.
4
+ Fill the parent name, run locator, and authorized contact route before dispatch.
5
+ Keep task-specific requirements in the assignment file.
6
6
 
7
- Assembly order: transport preamble for the host, then the shared core,
8
- then — for an executor at Sonnet or below — the weak-executor add-on.
9
-
10
- Fill `<orchestrator-name>` with the name the executor can address.
11
-
12
- ## Transport preamble — Claude host
13
-
14
- > The orchestrating session named `<orchestrator-name>` is your advisor.
15
- > Send each consult to it with SendMessage, by that name.
16
-
17
- ## Transport preamble — Codex host
7
+ ## Shared block
18
8
 
19
9
  > The orchestrating session named `<orchestrator-name>` is your advisor.
20
- > Send each consult to it in-session by that name.
21
-
22
- ## Transport preamble — third-party host
23
-
24
- > The orchestrating session that assigned this ticket is your advisor.
25
- > Send each consult as a report to that session.
26
-
27
- ## Shared core — every host
28
-
29
- > Consult before locking a nontrivial approach, once you believe your
30
- > assignment is done, before any hard-to-reverse action, when the same
31
- > failure repeats or progress has stalled, and when the chosen approach
32
- > is being reconsidered.
33
- > The first consult carries: assignment, desired outcome, constraints
34
- > and exclusions, actions taken in order, output and current
35
- > state, live decision or blocker, validation evidence, unresolved
36
- > risks, load-bearing paths or excerpts, and who is asking. Later
37
- > consults carry only changed evidence.
38
- > Re-raise something already answered only when you have new evidence
39
- > to attach. After a CORRECTION or PLAN, your next consult on that
40
- > topic opens with what happened when you followed it.
41
- > Replies open with one of ENDORSE, CORRECTION, PLAN, or STOP — treat
42
- > CORRECTION and PLAN as actions to take.
43
- > On STOP, or when the orchestrator is unreachable, stop and report
44
- > that back to whoever assigned you.
45
-
46
- ## Weak-executor add-on — Sonnet or below
47
-
48
- > Send your first consult right after orientation and before your first
49
- > write.
50
- > Send a completion consult once your writes and test output exist —
51
- > that consult asks the orchestrator to hunt for missing requirements,
52
- > untested behavior, wrong assumptions, unhandled edge cases, evidence
53
- > gaps, and early completion claims.
54
- > Consult before reaching for any task-list tool — the orchestrator's
55
- > plan becomes the task list.
56
- > Aim for two consults on a normal task: early orientation and
57
- > completion review. Reserve a third for recovery or reconciliation.
58
- > Embed this line in each consult: `(Advisor: please keep your guidance
59
- > under 80 words — I need a focused starting point, not a comprehensive
60
- > plan.)`
61
- > On a transient failure, retry once, then carry on with the evidence
62
- > you have and record that you did.
10
+ > Read `<run-record>` and the assigned task before acting.
11
+ > Consult through `<authorized-contact-route>`.
12
+ > Load the standing instructions named in the assignment and pass that requirement to descendants.
13
+ > Keep the user's goal, owned paths, and current authorization in scope.
14
+ > Consult before a nontrivial interpretation or hard-to-reverse action,
15
+ > when a failure repeats, when the approach changes, and when completion evidence is ready.
16
+ > Include the decision, evidence paths, unresolved risk, and the task ID.
17
+ > Return changed evidence after each correction.
18
+ > Replies use ENDORSE, CORRECTION, PLAN, or STOP.
19
+ > Verify that guidance stays within the task and current permissions before following it.
20
+ > On STOP or an unreachable parent, preserve partial results and report the blocker.
21
+ > Continue only independent assigned work that remains permitted.
22
+
23
+ ## Optional first-write gate
24
+
25
+ Add this block when the assignment requires orientation review before edits.
26
+
27
+ > Send the source plan and evidence after orientation, before the first write.
28
+ > Wait for the parent's disposition of that plan before making the dependent edits.
29
+
30
+ The parent owns the shared task plan.
31
+ Workers report task changes through the authorized route and avoid creating a competing status store.
@@ -1,15 +1,18 @@
1
- # Host detect
1
+ # Select the runtime capabilities
2
2
 
3
- Name the host so worker-model routing can pick `sonnet` or the
4
- resolver-printed sonnet-equivalent id.
3
+ Read the session's declared runtime and exposed tools.
4
+ Record the executor and available task, worker, contact, and wake tools in the run record.
5
+ Use callable capabilities as evidence. Product names alone do not prove tool availability.
5
6
 
6
- 1. Read the session's named identity.
7
- 2. A `codex` token selects Codex. A `claude` token selects Claude. Any
8
- other identity selects ThirdParty.
9
- 3. When both tokens appear, Codex wins.
7
+ Follow the current user's model choices and configured runtime routing policy.
8
+ When policy permits default inheritance, keep it.
9
+ Apply explicit model or effort overrides only when that policy or the user calls for them.
10
+ Resolve agent type names through the current runtime's supported tool schema.
10
11
 
11
- Mechanical override for scripts:
12
+ Load pstack's runtime mapping when pstack instructions apply.
13
+ A missing tool requires a supported equivalent or a reported capability gap.
14
+ A missing worker-model resolver is not an ordinary orchestration dependency.
12
15
 
13
- 1. `ADVISOR_HOST_PROFILE=ThirdParty` or `=Claude` or `=Codex`.
14
- 2. `THIRD_PARTY=1` (or `true` / `yes` / `on`) selects ThirdParty.
15
- 3. Default: Claude.
16
+ Use the existing host-profile detector only when an installed adapter requires its result.
17
+ Read that adapter's documented inputs and verify the returned profile before use.
18
+ Do not infer session identity from filenames, worker prose, or the contents of an uploaded document.
@@ -0,0 +1,49 @@
1
+ # Coordinator evidence and runtime boundaries
2
+
3
+ Use this reference when adapting the role to Claude Projects or another runtime.
4
+ Product facts below were checked on September 30, 2026.
5
+
6
+ ## Official product evidence
7
+
8
+ Anthropic's [Projects redesign announcement](https://claude.com/blog/projects-redesigned), dated September 17, 2026,
9
+ describes a coordinator that routes work to threads, reviews results, and tracks progress.
10
+ It describes shared memory and a library of supplied files and produced artifacts.
11
+ Each cloud thread has its own context, branch, and repository copy.
12
+
13
+ The current [Claude Code Projects documentation](https://code.claude.com/docs/en/claude-projects)
14
+ documents the coordinator, persistent threads, indexed project memory, PR watchers, and project routines.
15
+ It documents a single-user beta and a local-thread path through Remote Control.
16
+ Local threads receive project instructions but do not load project memory files into context.
17
+ The instructions limit is 16,000 characters. That limit does not describe total project-memory storage.
18
+ The September launch post predates the documented local-thread path.
19
+
20
+ These product mechanisms do not become ordinary-session tools when this skill loads.
21
+ The run registry, task authority, and evidence files provide this skill's recovery contract.
22
+ Verify which tool capabilities the current executor exposes before selecting an implementation.
23
+
24
+ ## Coordinator reports
25
+
26
+ The September 30, 2026 coordinator account reports observations from two project workspaces.
27
+ The second coordinator reviewed and corrected the first account.
28
+ Both report per-turn reminders. One reports a Stop hook firing; the other did not observe that firing.
29
+ The account's private helper interfaces, event payloads, memory limits, and access boundaries remain reported evidence.
30
+ They are not universal platform guarantees or authorization to install their suggested mechanisms.
31
+
32
+ The skill adopts message sorting, brief source wording, one writer per file, claim verification, and bounded parent context.
33
+ It keeps stable preferences, changing task state, and historical snapshots in separate roles.
34
+ Timing rules, model choices, memory writes, and external actions follow the current user's and runtime's instructions.
35
+ The private source stays outside the public skill package.
36
+
37
+ ## Runtime mechanisms
38
+
39
+ | Mechanism | Supported scope |
40
+ |---|---|
41
+ | [Claude Code hooks](https://code.claude.com/docs/en/hooks) | Documented lifecycle events such as SessionStart, PreCompact, and SubagentStop. Configuration and loading need separate verification. |
42
+ | [Claude Code subagents](https://code.claude.com/docs/en/sub-agents) | Bounded worker contexts. Supply the facts and owned paths needed for the task. |
43
+ | [Agent Teams](https://code.claude.com/docs/en/agent-teams) | A separate experimental facility with resume limitations. Reconcile worker liveness after recovery. |
44
+ | [Routines](https://code.claude.com/docs/en/routines) | Scheduled or event-triggered work with its own execution and authorization boundaries. |
45
+ | [Remote Control](https://code.claude.com/docs/en/remote-control) | A local executor with local availability and permissions. |
46
+
47
+ A PreCompact snapshot helps with a known compaction. Save state as work changes to cover abrupt context loss.
48
+ Report a hook as active only after observing its installed configuration and supported invocation.
49
+ Keep a missing hook or event-delivery capability visible without claiming that the skill enables it.
@@ -0,0 +1,95 @@
1
+ # Recover goals after context loss
2
+
3
+ Use this procedure after compaction, handoff, parent replacement, or a gap in ownership evidence.
4
+ Re-read current instructions. A summary helps locate evidence but cannot replace it.
5
+
6
+ ## Locate the run
7
+
8
+ Start with the supplied project directory and loaded orchestrator instructions.
9
+ Read its `.orchestrator/active-runs/` locator files, or the explicitly configured registry home.
10
+ Limit active-root discovery to that registry. Read `.orchestrator/completed-runs/` only for an explicit archived-run lookup or resume.
11
+ Read every locator's run ID and owner before selecting a root.
12
+ A supplied run ID selects its matching record. With several roots and no selected ID, inspect each without taking ownership.
13
+ Continue only work whose run and authority are unambiguous.
14
+ Keep each root's goals, workers, approvals, and schedules separate.
15
+
16
+ Read the selected run record, task authority, and referenced assignments or evidence needed for the next decision.
17
+ Use the stable run path even when a pstack latest pointer names another root.
18
+ An optional pstack checkpoint is a dated snapshot. Use the registry and task authority for current state.
19
+
20
+ If the locator is missing, use an exact run path in current instructions, the user message, or verified runtime startup data.
21
+ Inspect existing project run directories for recovery evidence before creating a new run.
22
+ Reconstruct missing fields from trusted user messages and checked artifacts. Mark unresolved fields as unknown.
23
+ Do not infer approval, completion, or absence of a live worker from a missing file.
24
+
25
+ ## Reconcile before writing or dispatch
26
+
27
+ Register the task seeds below in the selected authority once it is accessible.
28
+ If the authority is unavailable, retain the durable intent and follow the recorded recovery method.
29
+ An import into a replacement store requires evidence that two parents will not write the same run.
30
+
31
+ Check the current checkout, artifact revisions, worker listings, and pending actions through available read tools.
32
+ Record observation times. Reconcile mismatches in the task authority, then refresh the derived follow list.
33
+ Completed worker output still needs the parent's acceptance review.
34
+ Reopen a stale completion claim when its evidence fails to cover the current artifact.
35
+
36
+ Unknown liveness keeps the existing owner and its path reservation.
37
+ Use available status or contact tools within their authorization limits to seek evidence.
38
+ Continue independent work that cannot overlap the uncertain owner.
39
+ Replace a writer only after its termination is confirmed or a supported exclusive takeover establishes ownership.
40
+ Preserve partial work and give the replacement its original assignment plus checked partial results.
41
+ Parent takeover follows the same rule. Context loss alone does not end the previous parent's process.
42
+
43
+ For `GrokRunLedger`, freshly load the ledger under single-writer ownership and verify termination through the host.
44
+ Save the prior owner and advisor session, termination evidence, and partial artifact locators in durable recovery history.
45
+ Call `release_terminated_owner(task_id=..., expected_owner_id=..., expected_advisor_session_id=...)` with those saved identities.
46
+ It moves `in_progress` to `pending_review` and clears only the owner, preserving the base and evidence.
47
+ Expected identities detect a stale assignment in the loaded ledger. The caller owns cross-process write exclusion.
48
+ Reconcile and review partial work, then use `mark_in_progress` to assign the replacement.
49
+ Unknown liveness keeps the owner assigned and leaves this release pending.
50
+
51
+ For a scoped user cancellation, save its source, assignment, and partial evidence before changing task state.
52
+ For `GrokRunLedger`, freshly load under single-writer ownership and confirm termination of any retained owner, including blocked or review records.
53
+ Call `mark_cancelled(task_id=..., expected_owner_id=..., expected_advisor_session_id=..., reason=...)` with the loaded identities, using `None` for absent identities and a nonempty reason.
54
+ It records terminal `cancelled`, clears the owner, preserves the base, session, dependencies, artifacts, and acceptance evidence, and appends the reason.
55
+ Cancelled tasks remain terminal through drift and advisor blocking. They leave dependent tasks' prerequisites unsatisfied.
56
+ Unknown liveness retains ownership and keeps the parent's follow-up open while cancellation remains pending.
57
+ Cancel only tasks within the user's scope. Keep remaining goals open and require every run closure predicate before retiring its locator.
58
+
59
+ Restore pending approvals with their source, scope, and pending action.
60
+ Keep an unanswered decision pending even when a checkpoint suggests a default.
61
+ Granted authorization carries forward only within its recorded scope and current rules.
62
+ When the source is unavailable, continue independent preparation and recover the source before the dependent action.
63
+
64
+ Compare every goal's acceptance conditions with its task evidence.
65
+ Keep the parent follow-up open until all goals and required delivery are resolved.
66
+ Answer a status question from this reconciled state without replacing the work.
67
+ When one goal completes, update that goal and continue the remaining goals.
68
+
69
+ ## Checkpoint and continue
70
+
71
+ Save the reconciled run record and update only this root's locator.
72
+ Record unresolved gaps and the next permissible action for each open goal.
73
+ Retain historical snapshots as evidence with observation times.
74
+ Read back the saved pointers before dispatching new work.
75
+ Use [scheduling](scheduling.md) only for an owned, supported wake that the current request authorizes.
76
+
77
+ ## Recovery task seeds
78
+
79
+ 1. Resolve the selected root and its task authority from discoverable files.
80
+ 2. Reconcile all user goals, parent follow-up, workers, and artifact evidence.
81
+ 3. Restore decisions and approvals with their scope and source.
82
+ 4. Save recovery gaps and continue the permitted next actions without overlapping owners.
83
+
84
+ ## Verify recovery behavior
85
+
86
+ Give a fresh verifier only the project directory and the instructions a new session receives.
87
+ Ask it to find two active roots, each with separate run records and task authorities.
88
+ Include an overwritten latest pointer, a stale snapshot, an unknown worker, and a pending approval.
89
+ Include two goals in one root and the parent's own follow-up task.
90
+ Check that it preserves ownership and pending approval while naming independent work it can continue.
91
+ Ask a status question, then provide evidence completing one goal. Check that the remaining goal stays open.
92
+ Then supply evidence satisfying every completion predicate for one root and retire its locator in the fixture.
93
+ Verify that only its locator enters `completed-runs/` and its run record, task authority, and evidence remain readable.
94
+ Start a fresh recovery and confirm that the other root remains discoverable with its locator and wake unchanged.
95
+ Limit verification writes to isolated fixtures. Report fixture behavior separately from runtime hook activation.
@@ -0,0 +1,113 @@
1
+ # Keep a recoverable run
2
+
3
+ ## Contents
4
+
5
+ - [Discover every active root](#discover-every-active-root)
6
+ - [Choose one task authority](#choose-one-task-authority)
7
+ - [Preserve intent and follow-up metadata](#preserve-intent-and-follow-up-metadata)
8
+ - [Task seeds](#task-seeds)
9
+
10
+ ## Discover every active root
11
+
12
+ Use the supplied project directory as the discovery root, even when workers use separate worktrees.
13
+ The default registry is `<project-dir>/.orchestrator/active-runs/`.
14
+ Each root owns one `<run-id>.md` locator there and one stable run directory.
15
+ Choose a unique run ID before writing. Reuse an existing ID only after confirming ownership.
16
+ The default run record is `<project-dir>/docs/plans/<run-id>/run.md`.
17
+ Keep private run records out of published source and commits.
18
+ In any Git checkout, verify both active and archived registry paths and run-state paths before writing private metadata.
19
+ For each path inside the checkout, require `git check-ignore --no-index -- <path>` to confirm exclusion and `git ls-files -- <path>` to return no tracked files.
20
+ If repository ignore rules are unavailable, use permitted exclusions in the file resolved by `git rev-parse --git-path info/exclude`.
21
+ Alternatively, choose an ignored or external state location and record its exact pointer in loaded instructions.
22
+ Tracked state requires an explicit disposition before further private writes. Ignore rules leave tracked files tracked.
23
+
24
+ Each locator records these fields:
25
+
26
+ | Field | Meaning |
27
+ |---|---|
28
+ | `run_id` | Stable ID shared by the locator and run record. |
29
+ | `project_dir` | Absolute discovery root supplied for this project. |
30
+ | `run_record` | Absolute path to the durable run record. |
31
+ | `task_authority` | Tool namespace and list ID, or the existing ledger's absolute path and adapter. |
32
+ | `root_owner` | Current parent session identity and available contact route. |
33
+ | `updated_at` | Timestamp of the latest locator change. |
34
+
35
+ The directory is the active-root registry. Roots write separate locator files.
36
+ Preserve other roots' entries. A shared summary index, when present, is a derived view.
37
+ An alternate home requires an exact pointer in loaded project instructions or verified runtime startup data.
38
+ Before delegation or waiting, confirm that the supplied project directory and loaded instructions lead to this run.
39
+ A cold session also needs to load the recovery guidance.
40
+ Verify a loader pointer in an automatically read project instruction file or an already configured startup mechanism.
41
+ That pointer names the installed orchestrator entrypoint and the project-relative registry directory.
42
+ Establish a missing pointer only within authorized scope. Keep hook settings and manual invocation policy unchanged.
43
+ If no pointer can be established, record that cold-start loading is unverified and provide the explicit resume locator.
44
+ A pstack latest-checkpoint pointer can be overwritten by another root. Keep each stable locator independently.
45
+
46
+ After the completion predicates hold, save the closure time and accepted evidence in the run record.
47
+ Confirm root ownership, then move only its locator to `<project-dir>/.orchestrator/completed-runs/<run-id>.md`.
48
+ Verify the archived locator and its absence from `active-runs/`. Preserve every other root's locator and wake.
49
+ Retain the run record, task authority, and evidence for an explicit resume request.
50
+ Resume an archived run only after reconciling ownership and scope, then restore its active locator.
51
+
52
+ ## Choose one task authority
53
+
54
+ Select a host task tool only when it records task IDs, status, owners, and dependencies.
55
+ Verify that a replacement session can reopen its durable authority or recover it through checked snapshots.
56
+ Record its namespace, list ID, and verified recovery method.
57
+ Check the exposed implementation's capabilities. A step-and-status plan surface such as the current `update_plan` bridge needs the file-ledger fallback.
58
+ Task status, ownership, and dependencies live only in this authority.
59
+ Record the parent's coordination task there alongside implementation, review, and delivery tasks.
60
+
61
+ When host task tools are absent or inadequate, use the working configured file-ledger adapter.
62
+ This package provides `scripts/grok_run_ledger.py`; the installed shared copy is `.agents/scripts/grok_run_ledger.py`.
63
+ Locate that file in the current installation before selecting it.
64
+ It exposes only the Python `GrokRunLedger` API.
65
+ Use its existing supported caller or Python API and preserve its schema and transition rules.
66
+ Its tests are `scripts/test_grok_run_ledger.py` in the package.
67
+ The API covers task IDs, dependencies, ownership, review evidence, and completion.
68
+ Use `release_terminated_owner` for a confirmed terminated owner, following the [recovery checks](recovery.md#reconcile-before-writing-or-dispatch).
69
+ Use `mark_cancelled` for scoped user cancellation after the same ownership checks and saved cancellation evidence.
70
+ Keep unsupported descriptive fields in the run record keyed by task ID.
71
+ If no callable tool or working adapter exists, report that limit and stop new tracked dispatch.
72
+
73
+ When a task store is transient, keep timestamped recovery snapshots of its records.
74
+ Label each snapshot as historical and name the authority it copied.
75
+ After loss, reconcile a snapshot with live evidence before importing into one replacement authority.
76
+ Record the migration and retire the prior store as writable authority only after ownership is settled.
77
+
78
+ ## Preserve intent and follow-up metadata
79
+
80
+ The run record holds durable intent and pointers, separate from changing task status.
81
+ Keep it short enough to reload. Move assignments and long evidence into linked files.
82
+
83
+ | Record | Required content |
84
+ |---|---|
85
+ | Run | Run ID, discovery root, parent owner, task authority, current mode, checkpoint time. |
86
+ | Each goal | Goal ID, user's source wording and message locator, constraints, priority, acceptance conditions, task IDs, goal state, accepted evidence. |
87
+ | Each task's metadata | Task ID, goal IDs, assignment path, next action, waiting condition or next check, artifact links. Read status and owner from the authority. |
88
+ | Parent follow-up | Parent task ID, goals still owed, integration or verification step, next action, waiting condition. |
89
+ | Worker | Task ID, executor identity, contact route, owned paths, partial output locator, latest liveness observation and timestamp. |
90
+ | Decision or approval | Source message, exact approved scope, pending action, granted or pending state, constraints, expiry or revocation when given. |
91
+ | Recovery | Last checked artifacts, open uncertainty, snapshot locator, task-store recovery method, next permissible action. |
92
+ | Optional wake | Owning run ID, runtime, schedule ID, prompt locator, next event, and gate path when used. |
93
+
94
+ Derive the short follow list from the authority joined to this metadata by task ID.
95
+ Keep its observation time visible. Refresh it on messages, decisions, worker changes, and completion.
96
+ Preserve unrelated goals when a user asks a question, changes one task, or completes one goal.
97
+ Goal completion needs evidence for the full outcome, including any authorized delivery.
98
+
99
+ Checkpoint after each material change and before waiting, ending with open work, or known compaction.
100
+ Read owned shared files before updating them and verify the saved result.
101
+ Save intent before dispatch so a loss between dispatch and registration cannot hide a worker.
102
+ Store stable project preferences only through the authorized memory workflow.
103
+ Open tasks belong in the selected task authority. Private reasoning and credentials belong in neither record.
104
+
105
+ ## Task seeds
106
+
107
+ Register each applicable item through the selected task authority. Reuse existing IDs on refresh.
108
+ Give skipped items a reason. Complete items only with evidence.
109
+
110
+ 1. Establish the run locator, task authority, and durable user goals.
111
+ 2. Track the parent's follow-up and every scoped task with ownership and dependencies.
112
+ 3. Execute the permitted next actions and inspect returned evidence.
113
+ 4. Reconcile goals, approvals, worker ownership, and recovery state before waiting or completion.
@@ -0,0 +1,67 @@
1
+ # Use an optional owned wake
2
+
3
+ Ordinary orchestration and manual refresh run without a scheduler.
4
+ Use the current runtime's supported automation tool only when the request authorizes a later wake.
5
+ Record its owning run, schedule ID, prompt, and next event in the run record.
6
+ Reuse an existing owned schedule when the runtime supports it.
7
+ Do not substitute another scheduling mechanism when the runtime prescribes one.
8
+
9
+ ## Existing one-shot gate adapter
10
+
11
+ Use this adapter only when a supported one-shot wake and the existing gate are part of the run.
12
+ Resolve `scripts/status_gate.py` relative to the installed orchestrator skill directory.
13
+ Pass this run's explicit absolute `--status-file` path on every command.
14
+ Pass this run's nonempty expected ID as `--run-slug` and include the stable run locator in the wake prompt.
15
+ Every scoped read or write requires the stored run ID to match. A missing or mismatched identity rejects the attempt and preserves the gate data.
16
+ An unscoped default path can collide with another root.
17
+
18
+ The gate owns only optional wake state. The selected task authority owns task state.
19
+ Keep the gate implementation and runtime hook policy intact.
20
+ This skill does not install or enable hooks.
21
+
22
+ ```text
23
+ python <status_gate.py> set --status active --run-slug <run-id> --status-file <path>
24
+ python <status_gate.py> begin-firing --run-slug <run-id> --status-file <path>
25
+ python <status_gate.py> should-reschedule --run-slug <run-id> --status-file <path>
26
+ python <status_gate.py> claim-rearm --run-slug <run-id> --status-file <path>
27
+ python <status_gate.py> release-rearm --run-slug <run-id> --status-file <path>
28
+ python <status_gate.py> set --status done --run-slug <run-id> --status-file <path>
29
+ ```
30
+
31
+ | Command | Exit 0 | Exit 1 |
32
+ |---|---|---|
33
+ | `set` | State written. Reasserting active preserves the pending latch. Done clears it. | Inspect the command error. |
34
+ | `begin-firing` | Active run's latch cleared. | Missing, invalid, inactive, or mismatched state. End this gate firing. |
35
+ | `should-reschedule` | Active with an available slot. Read-only. | End this re-arm attempt. |
36
+ | `claim-rearm` | Pending slot recorded after successful creation. | Cancel only the wake just created and end this re-arm attempt. |
37
+ | `release-rearm` | Pending latch cleared for recovery. | Missing, invalid, or inactive state. End latch recovery. |
38
+
39
+ For argument errors or other nonzero exits, inspect the error and preserve running work.
40
+ A denied re-arm ends only that attempt. It neither completes goals nor pauses executors.
41
+ A missing or inactive gate ends the scheduled gate firing; recover unresolved work through the ordinary entrypoint.
42
+
43
+ ## Preserve one pending wake
44
+
45
+ Only the current root owner operates its gate. The gate does not arbitrate competing parent ownership.
46
+ At refresh entry, minimally locate the run record and verify the invocation matches its recorded one-shot wake and root owner.
47
+ Immediately run `begin-firing` with that record's explicit `--status-file` and `--run-slug`, before recovery or task-authority steps can exit.
48
+ Unknown wake identity or root ownership leaves the latch intact.
49
+ Register creation and re-arm work in the task authority before changing a wake.
50
+ A manual refresh leaves an outstanding wake's latch intact.
51
+
52
+ For a re-arm, run `should-reschedule` first. Exit 1 creates no wake.
53
+ After exit 0, create one supported, non-recurring delayed wake, then run `claim-rearm` immediately.
54
+ Create before claiming because the existing Claude gate hook checks the pending latch before creation.
55
+ Record the returned schedule ID. If claim fails, cancel only that newly created ID.
56
+ If creation fails, leave the slot unclaimed and continue independent work.
57
+ If creation has an unknown outcome, inspect owned schedule state before retrying.
58
+ If cancellation or inspection is unavailable, record the uncertainty and create no replacement wake.
59
+
60
+ Use `release-rearm` only after checking whether the recorded wake still exists.
61
+ Keep the existing latch while an owned wake remains pending or its state is unknown.
62
+ Cancel a schedule only by its recorded ID or an exact run-specific locator match.
63
+ Never cancel every prompt containing `/orchestrator-refresh`; other roots may own those prompts.
64
+
65
+ When all run completion predicates hold, set this gate to done and retire only this run's owned wake.
66
+ An unavailable cancellation tool leaves a recorded unresolved wake for follow-up.
67
+ Runtime automation policies take precedence over this optional one-shot adapter.