@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/CHANGELOG.md

@@ -1,3 +1,134 @@
+## [0.81.40] - 2026-07-24
+
+### Added
+
+- Added one targeted `accept:core-workflows` gate covering active-worker crash/restart fencing, simultaneous durable writers, repeated compaction/reopen cleanup, provider-neutral routing/reasoning/result/retry contracts, and adversarial UAC omission without running the full test suite.
+- Added owner-authored orchestration profiles with pinned model/thinking/tool/resource/budget policy, architect-owned worker allowlists, durable DAG attempts and fenced typed results, exact-session process-worker resume, and a constrained direct-argv `run_process` launcher for execution profiles.
+- Added one event-driven native interaction layer for human questions, task steps, and worker lanes: batched single/multi-select questions with unrestricted custom text, clipboard image attachments, skip/review flows, grouped width-bounded work status, durable human worker labels/profile ids, quiet idle behavior, progressive evidence detail, and host-owned lifecycle across extension reload and session resume. Worker UAC excludes the question tool before construction, and the legacy question examples now adapt this native contract instead of carrying two UI implementations.
+- Added a bounded session image store for clipboard attachments, configurable through `images.clipboardDirectory`, with stable numbered references that survive `/resume` and deterministic latest-image resolution for prompts such as “look at the image.”
+
+### Fixed
+
+- Fixed Windows startup migration of the NTFS `auth.json:Zone.Identifier` alternate data stream so its bytes move into bounded legacy state and the named stream is removed without rewriting the auth file.
+- Persisted one immutable admission-time worker execution contract across queueing, retry, restart recovery, and mandatory verifier recovery, so profile edits cannot silently switch a pending worker's model, thinking level, tools, execution policy, or resource identity; current host policy may still narrow the recorded authority.
+- Rebased durable-runtime startup tails onto a projection snapshot installed during the initial read, preventing a concurrent compaction from replaying post-snapshot events without their prefix.
+- Made durable orchestration replay and append fail closed on missing event ordinals, truncated tails, inaccessible storage, invalid snapshot idempotency data, and missing or changed published snapshots without reparsing an unchanged projection on every append.
+- Fenced process-matrix reconciliation, adoption, cleanup, self-owned heartbeat/exit, resumed-worker PID publication, terminal persistence, and delivery acknowledgement with one shared per-entry conditional-write contract so stale process generations cannot overwrite newer registrations.
+- Made session teardown, activation, and quit failures drain every cleanup step; replacement failures reconstruct and rebind the previous durable session, clean rejected candidate resources/artifacts, remain distinct from post-commit callbacks, and serialize process disposal behind any admitted replacement.
+- Made session replacement transactional through candidate preparation and awaited old-session resource shutdown, moved process/worktree supervision under the active session lifecycle, restored exact session+task workers only after goal activation, persisted late terminal notices for replay to the owning session, denied automatic recovery for mismatched or terminal goals, and bounded process-matrix retention.
+- Fenced overlapping session replacements and RPC prompt/replacement races, and made durable worker terminal notifications acknowledge delivery only after the bounded parent handoff is persisted; owner-question handoffs no longer spend a redundant model turn.
+- Made `/resume`, `--resume`, `--continue`, and exact `--session` restore a blocked goal through the same core persisted transition as `/goal resume`, before worker supervision starts.
+- Bounded durable orchestration persistence with immutable digest-verified projection snapshots, a count/byte-limited append-only event tail, bounded retained idempotency evidence, crash-safe pointer publication, and monotonic ordinals across compaction and concurrent-runtime catch-up.
+- Made owner-input requests crash-safe and transport-neutral: `ask_question` now checkpoints before display, uses the full multi-line editor without an answer-length clamp, RPC exposes the same fail-closed typed question protocol as the TUI, `/resume` replays the original tool-call id, large custom answers remain exact in bounded artifacts, RPC images are retained before checkpoint, client-forged artifact references are rejected, non-vision image submission fails visibly, and worker `ask-user` verdicts create deterministic parent requests instead of relying on prompt compliance.
+- Made the clipboard paste action match platform conventions (`Ctrl+V` on Unix/macOS, `Alt+V` on Windows, both on WSL), preserve ordinary text paste when no image is present, resize image payloads through the shared safety path, and keep default storage out of working directories.
+- Added a zero-write, single-namespace extension storage contract for durable state, rebuildable cache, and automatically released bounded work; extension loading now honors injected agent directories for transform cache and storage, while `pi doctor` reports unexpected root writers through a bounded read-only audit.
+- Contained directory profile overlays and configuration backups under canonical `profiles/` and `state/` namespaces, archived obsolete root scratch/Auto Learn layouts, and added bounded conflict-preserving migration with zero-write legacy reads.
+- Consolidated generated context payloads under one leased, bounded per-session work namespace; context/report inspection and unflushed session creation are now zero-write, recognized legacy stores migrate safely, and empty session namespaces are pruned without applying retention to transcripts.
+- Consolidated fitness, adaptation, and tool-selection host state behind one validated lock-safe atomic store; concurrent sessions no longer overwrite profile or tool evidence, and worker read-only mode remains zero-write.
+- Extracted managed tmux-worker lifecycle and claim review from the background coordinator, made managed and in-process workers share one durable task runtime and terminal outbox without materializing a withheld execution controller, required every managed dispatch to carry its fixed profile, authorization, instruction, provider, turn, lease, tool, path, and budget contract, persisted the full compiled execution grant before process/prompt side effects, rejected scope-changing follow-ups, removed the extension's duplicate parent wake path, removed the research controller's circular dependency on its parent, and renamed raw worker-claim modules so untrusted claims are no longer presented as durable results.
+- Consolidated failure-corpus, tool-recovery, and worktree-audit persistence behind one lock-safe bounded JSONL sink; worktree audit is no longer unbounded, concurrent failure-corpus rotation cannot lose appends, and worker terminal telemetry no longer masquerades as an accepted result.
+- Unified process supervision and durable orchestration on one logical-agent identity, pinned initial tmux workers and exact-session resumes to the same managed lane, and made resume prefer the persisted session file while rejecting divergent lane context.
+- Separated untrusted worker claims from host-fenced durable worker results, removed parallel result adapters, and made session, goal, status, telemetry, and review projections use the claim contract without implying worker self-report is accepted task truth.
+- Unified capability envelopes, profile grants, lane construction, runtime gates, research policy, and worker execution on one canonical capability vocabulary; equivalent grants such as `worktree.read` and `tests.execute` now survive through execution instead of failing a second translated gate.
+- Consolidated foreground envelopes, runtime gates, orchestration profile validation, and lane manifests behind one tool-capability policy catalog; active network, skill, source, verifier, and status tools no longer disappear from capability visibility while separate authorization tables drift.
+- Unified goal and durable-objective acceptance/lifecycle transitions: every satisfied requirement now needs its own trusted proof, goal pause/resume/cancel/complete reconciles already-loaded worker execution without defeating lazy UAC, terminal objectives cancel residual attempts with explicit reasons, and worker terminal publication has one idempotent path.
+- Consolidated goal requirements, foreground task steps, and delegated DAG work behind one identity-based read model; task steps now persist explicit requirement links, legacy text inference has one conservative fallback, and worker dispatch synchronizes durable objective acceptance criteria without treating worker self-report as proof.
+- Consolidated versioned session snapshot persistence, validation, defensive cloning, list reads, latest reads, and branch-ancestry fallback behind one typed codec shared by goal, task, evidence, learning/audit, lane, and worker state; live accessors and review acknowledgements now read one active branch while diagnostics retain explicit whole-session history, and domain validators share explicit plain-record and general record-object guards.
+- Consolidated worker admission, profile/verifier resolution, capability checks, durable attempt preparation, and resumed lane-id allocation so immediate, queued, recovered, and scheduler-revalidated dispatches share one policy contract, durable tasks are the sole identity source, and a lifecycle instantiated before late durable writes cannot reuse an existing lane id.
+- Unified managed-worker identity across dispatch, goal binding, persistence, reload recovery, and terminal reporting; running tmux lanes now restore under the same durable id instead of degrading into indeterminate bindings after `/reload`.
+- Persisted per-check compaction verification score ranges across retry fallback and surfaced them in session analytics and `/usage` diagnostics.
+- Made foreground prompt preparation transactional: routing events stay balanced, failed extension preflight retains pending `nextTurn` context, queued messages cannot reset active-turn cost accounting, and pre-start execution failures release early-painted message identities.
+- Consolidated terminal foreground response handling behind one recovery coordinator with deterministic transient retry, quota failover, retry closeout, compaction, and queued-continuation ordering.
+- Consolidated manual and automatic compaction detection, execution, retry, cancellation, persistence, and extension notification behind one controller with a shared result-application path and provider-neutral policy types.
+- Consolidated foreground model tool-protocol selection, probing, calibration, circuit breaking, repair teaching, and turn-local telemetry into one controller shared by session call sites.
+- Made execution policy a mandatory durable pre-lease gate: approvals and owner notifications now replay, approval never grants authority without a newly compiled grant, paused objectives cannot start or resume work, and workers bind their grant before entering leased/running state.
+- Split goal auto-continuation, autonomous research, model-fitness probing, and shared lane-model resolution into single-owner controllers, leaving the background facade responsible only for composition and the separate managed-lane bridge.
+- Moved durable worker scheduling, execution, recovery, verification, and terminal notification behind one controller; capacity-bound workers now queue consistently across providers, owner-pinned verifier profiles run automatically before acceptance and retry event-driven recovery after temporary admission failures, and dead Pi workers resume the exact persisted session and logical-agent identity with checkpoint/resource handoff.
+- Consolidated worker profile resolution, risk classification, capability grants, execution budgets, lifecycle state, structured-action enforcement, and terminal notifications behind single-owner contracts; removed delegate/settings authority overrides, made undelivered in-process terminal handoffs resume-safe, and enforced trusted acceptance evidence before task/objective completion.
+- Made out-of-process managed workers emit the same bounded event-driven terminal handoff as in-process delegates, taught models to retrieve results once after that handoff instead of polling, and let unprofiled background lanes use the selected model's declared or provider-agnostic reasoning default.
+- Unified foreground startup, background-lane defaults, and isolated-completion clamping through the shared provider-neutral model capability resolver.
+- Made foreground and isolated worker tool routing share the same calibrated text-protocol variant instead of silently forcing subagents onto the default dialect.
+- Classified process-matrix/tmux children as workers from their parent identity, and applied worker/resource-profile UAC before built-in/override tool construction and live extension import, so withheld tools invoke no runtime factory and denied extensions load no module code.
+
+## [0.81.39] - 2026-07-20
+
+### Added
+
+- New `processMatrix` system (on by default, `processMatrix.enabled: false` is the explicit opt-out): a durable, restart-surviving master/worker process matrix under `state/process-matrix/`. A worker launched with a known parent (`PI_PARENT_PID`/`--parent-pid`, threaded automatically through `tmux_agent_manager`'s `fire_task`) self-registers and watches its parent's liveness; on parent death it winds down gracefully (never silently), leaving a resumable payload, and either gets adopted by a new master or self-exits after a bounded grace window. A master's startup scan for orphaned workers ALWAYS asks the owner before touching anything (adopt, cooperative cleanup, or leave untouched) and is report-only with zero writes/kills when non-interactive — see `docs/process-matrix.md`.
+- Closed the tool-selection observe/promote loop: durable per-(model, intent) agreement tracking, an evidence-gated compact prompt hint (activates only past utility/margin/min-evidence thresholds, deactivates when its tracked efficacy drops, never auto-executes), a `getReport()` surface joined into `/toolhealth`, and `PI_TOOL_SELECTION_OBSERVE` / `PI_TOOL_SELECTION_HINTS` kill switches.
+- Goal evidence now carries a validated ref and a `verified` flag: `add_evidence` checks a "tool" ref against real session tool-call records or a "file" ref against the filesystem, and marking a goal `complete` requires at least one satisfied requirement backed by verified or user-confirmed evidence (configurable, default on).
+- Delegated workers whose mutation needs a human look are now observable and sticky in `delegate_status` instead of purely advisory text: an unreviewed-mutation notice persists until the parent explicitly acknowledges it via a new `delegate_status` review action. Enforcement stays visibility-only, never write-blocking.
+- Goals now carry a durable, per-goal cumulative continuation budget (turns, active wall-clock, and attributed USD spend) across every continuation invocation for the goal's lifetime, with a conservative default ceiling and a visible `goal_budget_exhausted` stop reason.
+- A turn-boundary advisory nudge fires when the task_steps workflow contract (one in_progress step, no stale open steps) is violated for 3 consecutive turns — a one-line harness note, never a blocking gate.
+- The goal continuation snapshot and prompt now include a read-only summary of open task_steps steps, and satisfying or completing a goal requirement nudges when an open task step appears to reference it — read-only cross-visibility between the goal and task-steps systems, with no shared state machine.
+- A canonical, typed path module (`agent-paths.ts`) is now the single source of truth for everything machine-managed under the agent directory (`state/`, `cache/`, `work/`, runtimes, models, sessions, npm/git installs); an idempotent startup migration relocates the confirmed root-level straggler (`trust.json`) into `state/`.
+- tmux workers launched via `tmux_agent_manager` are now PERSISTENT and talkable mid-run: a new `send_followup` action re-injects a fresh prompt into an already-live job's pane using a unique per-turn marker pair and re-arms the pane's completion watcher, reusing the existing event-driven per-turn handoff; session start now also reconciles tmux sessions against this session's own job records (an orphaned session is marked informational, never killed; a live session with a pending turn has its watcher re-armed); a new `dismiss` action stops tracking a job without killing its tmux session, and an idle worker (no turn currently dispatched) no longer holds a reload-quiesce registration.
+- tmux worker dispatch is now approval-gated by a persisted, per-session/per-goal STANDING GRANT: `grant_dispatch` (interactively confirmed, or opt-in via `--allow-tmux-dispatch` with no UI) authorizes repeated unattended `fire_task`/`send_followup` launches within a budget (`maxLaunches`, optional expiry, goal/tool/path scope); `revoke_grant` ends it early; a launch with no covering grant and no interactive approval is refused, never silent. A grant-covered `pi` child is launched with a restricted profile (`--tools`/`--resource-profile` or `--no-extensions --no-skills`, plus a scoped `--append-system-prompt` naming the grant and its hard stops) pushed into the child's own launch configuration; non-`pi` agents are bounded at the launch layer only. Self-reported worker usage is ingested as an advisory, idempotent claim (`reportSpawnedUsage`), never a hard cross-process cap.
+- A new host bridge (`pi.reportManagedLane`) makes out-of-process tmux workers first-class `tmux-worker` lanes: visible in `/autonomy` and `delegate_status` alongside in-process worker lanes, reload-quiesce-registered only while a turn is dispatching, and left as a bounded claim snapshot on terminal. A tmux worker's self-reported changed files are re-checked against the session's active write scope and flagged for parent review when out of scope (reusing the existing in-process worker review path verbatim); in-process worker lanes are now goalId-tagged, matching the existing research-lane tagging.
+- Goals gain a `worker` evidence kind (verified against the worker's lane/result and its review flag, so an unreviewed worker completion can never ungate goal completion) and a structural `dispatch_worker` action that records a requirement↔lane binding without silently satisfying the requirement; the binding and worker-evidence verification are wired live (dispatches a real in-process worker lane today — tmux-worker selection from this tool is not yet available).
+- The goal loop no longer stalls out or races a redundant re-dispatch when a worker is actively handling an open requirement: a new `waiting` continuation state (reason `worker_in_flight`) pauses the loop without submitting a hollow pass and stops the idle scheduler from re-dispatching, resuming automatically once the worker's lane goes terminal; per-goal worker/subagent spend is now tracked (`continuationWorkerSpendUsd`, summed from the goal's own lanes) against a new conservative default ceiling, accurate for in-process lanes today and advisory for tmux workers pending a documented follow-up.
+- The goal tool's `dispatch_worker` action can now target a persistent tmux worker instead of the default in-process one (`dispatchTarget: "tmux"`, opt-in per call): core structurally invokes the tmux extension's `fire_task` itself — the same tool call the model would make — single-agent and 1:1 to the requirement's bound lane, still gated by the existing standing-grant authorization; an unattended dispatch with no covering grant is honestly refused (`dispatchSkipReason: "no_standing_grant"`), never silently launched and never a fabricated lane id. Correlating the extension's own dispatch report back to the internal lane id is a new deterministic keyed lookup (`BackgroundLaneController.resolveManagedLaneId`), not a racy lane-list diff.
+- New `worktreeSync` system (on by default, `worktreeSync.enabled: false` is the explicit opt-out): a hard-gated, worktree-per-lane parallel-work workflow (`worktree_sync` tool: `status`/`create_lane`/`sync`/`continue`/`abort_sync`/`land`/`release_lane`/`reconcile`) where every writing agent works in its own git worktree/branch and integration is always rebase-onto-main + fast-forward, serialized under one integration lock with a configurable land-time gate command verified at the exact landing tip — see `docs/worktree-sync.md`. Wired into the goal loop and tmux dispatch: two new continuation reason codes (`lane_sync_required`/`lane_sync_conflict`) give the goal loop a deterministic directive when a bound worker's lane is stale or has a rebase stopped on conflicts; the goal runtime snapshot can surface per-requirement worktree lane state; a goal-bound tmux dispatch (`dispatchTarget: "tmux"`) creates the lane FIRST when worktree-sync is enabled, aborting cleanly before any tmux launch on a creation refusal (`dispatchSkipReason: "worktree_create_failed"`), and launches the worker with `--worktree-lane <key>` plus one extra lane-doctrine system-prompt clause; `LaneRecord` gains an optional `worktreeLaneKey` so `/autonomy` and the goal snapshot can render the pairing.
+- A new session-role identity (`core/session-role.ts`) gives a worker session (lane-bound or `PI_SESSION_ROLE=worker`) a strict UAC ceiling: `goal`/`delegate`/`delegate_status`/`improvement_loop`/`extensionify`/`skillify`/`run_toolkit_script`/`model_fitness`/`tmux_agent_manager`/`context_scout`/`python` can never activate, wins over any allow-list or resource-profile grant; `worktree_sync`'s `create_lane`/`release_lane`/`reconcile` are refused and `land` is deny-by-default (new `worktreeSync.workerLand` setting) for a worker, which may only ever target its own bound lane; `land`/`release_lane` now refuse `lane_owner_conflict` when a different, still-alive session owns the target lane; a lane-bound session's `edit`/`write` targets are checked (symlink-safely) against the lane's own worktree root, refusing `path_outside_lane`; and every scattered on-disk store plus `SettingsManager`'s write path go read-only for a worker session, so no worker ever touches `~/.pi/agent/state` or `settings.json` — see `docs/worktree-sync.md`'s "Identity, UAC, and zero footprint" section.
+- Lane-worker eligibility now rides the model-capability system end to end (`evaluateLaneWorkerRefusal` in `core/model-capability.ts`): a worktree-sync lane worker requires capability class `full`, a declared registry context window, an advertised native tool-call path (`Model.textToolCallProtocol` unset/false), and no graded `/toolprobe` demotion to text-protocol/none — a goal→tmux dispatch refuses early as a best-effort check (`dispatchSkipReason: "worker_capability_insufficient"`, zero lane/pane side effect) and the dispatched child session refuses authoritatively at its own startup with a deterministic, greppable log line, regardless of how it became lane-bound. The lean capability class also now blocks the full orchestration surface (`goal`, `worktree_sync`, `improvement_loop`, `extensionify`, `skillify`, `model_fitness`, `context_scout`, `tmux_agent_manager`) in addition to `delegate`/`context_audit` — see `docs/worktree-sync.md`'s "Capability adaptation" section.
+
+- The Windows `bash` contract now routes through three tiers instead of one: the existing simple-command PowerShell floor (unchanged), a new bundled Python shell engine (uv-provisioned Python 3.13) for pipelines, redirection, chaining, quoting/expansion/globs, and the coreutils vocabulary, and named fail-closed refusals for constructs outside that grammar (job control, process substitution, arithmetic expansion, heredocs, nested shells, control-flow, `eval`/`source`/similar, and more) — see `docs/windows.md`. State-mutating commands (`cd`, `export`, `unset`) always route to the engine, the sole mutator; working directory and environment persist across calls and across tiers, with subshells (`( … )`) isolated and brace groups (`{ …; }`) sharing state like bash. A new `windowsShell.pythonEngine` setting (default `true`) is the hard kill switch: explicit `false` restores the prior PowerShell-only, simple-command-only contract verbatim. When the Python runtime cannot be resolved, the PowerShell floor keeps working and engine-only commands return a named, actionable degradation error instead of a silent wrong-approximation downgrade. Proven by a new engine conformance suite (Linux + Windows CI), a Linux-only differential oracle comparing engine output against real `bash -c` across the supported grammar, and Windows cross-tier integration tests exercising state handoff between the PowerShell and engine tiers.
+
+### Changed
+
+- Self-adaptation (native reflection + learning policy) is now on by default for a fresh session in every autonomy mode (off/safe/balanced/full) — evidence-gated (confidence threshold + `ObservationStore`). The preset lattice is monotonic: increasing autonomy no longer silently disables self-adaptation. All kill switches (`PI_NATIVE_REFLECTION=0`, `learningPolicy.enabled=false`, `AutoLearnSettings.enabled=false`) still disable it in every mode. The raw autonomy-prompt standing-grant authority block stays gated on `autonomy.mode` (`"off"` default unchanged).
+- The `delegate` tool's description and prompt guidelines now vary by wiring mode: an async start/poll contract when worker delegation is asynchronous, the synchronous contract otherwise.
+
+### Fixed
+
+- Bundled Python shell-engine source now keeps `BuiltinContext.stderr` optional for direct builtin callers, and its conformance/oracle tests parse the terminal control frame from stderr, matching the runtime transport.
+- Tmux dispatch grants now authorize and charge every launched child process; persistent follow-ups reserve their turn before pane injection to prevent duplicate external prompts after a crash. Process-matrix workers verify a fresh parent-session heartbeat alongside PID liveness, and worktree landing advances the named main ref with compare-and-swap recovery stages rather than merging whichever branch is checked out.
+- `/goal start` no longer double-fires its continuation loop: a single mutex now serializes the idle-driven and manual goal-continuation paths, eliminating both the "Agent is already processing" warning and an unhandled rejection that previously fired on effectively every `/goal start` (the idle auto-continue timer's default 0ms delay meant the manual and idle paths raced on nearly every invocation); the command layer gained try/catch parity and status-line handling for the new skip outcomes.
+- Task/goal state resolution (and the whole goal runtime snapshot: goal state, evidence, worker results, learning decisions) now walks the active session branch's own ancestry instead of scanning every branch's flat entry list — fork/branch-switch no longer leaks another branch's goal or task-steps state.
+- `task_steps`'s `add` action dedupes a retried add of an already-open duplicate step instead of creating a second copy (a legitimate re-add of previously completed work still creates a new step); a completed step with no evidence attached now surfaces a reminder in both the tool response and the injected per-turn context; and a `set`/`update` call that silently demotes another in_progress step to pending now names it in the response.
+- Goal stall detection now keys on satisfied-requirement and verified-evidence counts instead of raw event count, so hollow goal-tool calls that append events without making real progress can no longer defeat the stall guard.
+- Session disposal now durably persists canceled/in-flight worker lane records and a bounded worker result (including changed files) before the dispose cutoff, instead of losing them to an in-memory-only completion; queued (not-yet-started) workers are now visible to the reload quiesce gate from the moment they're enqueued, not just once running.
+- All goal-state free text rendered in the continuation prompt (the user goal, requirement text, blocked reason, evidence summaries, and the open task-steps summary) is now wrapped as untrusted data, matching the existing worker-result boundary — closing a prompt-injection vector reachable via a model's own `add_requirement`/`block_goal` calls.
+- The injected `task_steps_context` block is now GC-managed like `memory_context`, ending unbounded per-turn context growth for sessions with an open checklist; fixed a latent default drift between two independently hand-kept copies of the context-GC defaults (one was missing the `run_toolkit_script` tool, the other was missing `python`/`powershell`) by deriving both from one canonical source.
+- Runaway-loop stops and repeated tool-validation-failure escalations are no longer silent: both log a session entry; runaway stops surface a user-visible warning; validation escalation feeds the model router's existing cheap-route escalation gate. Isolated/reflection child loops inherit the runaway handler when on the foreground model.
+- Atomic, locked writes for model-adaptation, tool-recovery event-log rotation, the learning observation store, and skill-curator usage tracking (new shared `src/core/util/atomic-file.ts`); standing model-adaptation rules now also retire early once evidence shows they stopped reducing recurrence (in addition to the 30-day bound).
+- Reflection's automatic skill promotion runs the same `skill_audit` overlap check the `skillify` tool enforces; a near-duplicate draft is held as a consolidation proposal (learning-audit trail) instead of written.
+- Background/research/worker/reflection/fitness isolated-completion lanes carry a stable namespaced synthetic cache-affinity key (never the real session id), so provider session-affinity / `prompt_cache_key` caching actually hits on repeat lane calls.
+- The session cost guard folds this turn's background/spawned spend (per-turn baseline delta) into the same ceiling as the foreground projection (default action stays "warn"; per-lane caps untouched).
+- Spawned-usage accounting is idempotent: every `addSpawnedUsage` call site supplies a stable, content-derived `reportId`; the model-fitness probe threads its tool-call id as the idempotency token (separate deliberate runs count; retries dedupe).
+- `IsolatedCompletionOptions.cacheRetention` is required at the type level (silent "none" default removed).
+- Ollama/Transformers/prism readiness caching keyed per (server, model) instead of per-server — a second model on a confirmed server is never waved past the installed/residency checks. `LocalRuntimeController.reconcile()`/`dispose()` stops pi-spawned runtimes dropped from the live configuration on reload (detected-only servers never touched), wired into the reload path.
+- Compaction's summarizer honors managed-local readiness/residency for auto and manual `/compact`; also fixed a latent manual-`/compact` bug that dropped the resolved fallback model/failure and could pair a model with the wrong credentials.
+- Compaction pre-check accounts for this turn's own context-GC savings (read-only GC projection; suppression-only — near-full hard trigger unaffected).
+- Reload gate honors all in-flight work via a unified in-process quiesce registry (`reload-blockers.ts`): foreground streaming/compaction, research/worker/model-fitness lanes, context-scout runs, and isolated completions (registered at their single choke point).
+- Context-policy prompt-enforcement defaults now derive from the live context-GC settings (explicit values still win); corrected the stale GC-defaults doc comment (12/2500 → 8/1200).
+- Documented and test-pinned the system-prompt cache-stability invariant (one provider-cached block, rebuilt only on tool-surface change, day-granularity date).
+- A text-protocol ("phone") model that fails to parse the same tool-call signature 3 times in a row is now demoted to native fallback for real: the persisted tool-probe verdict itself is now cleared (was: only the cached protocol was cleared, leaving the phone flag on), which previously caused every subsequent turn to re-run up to 8 inline calibration completions before the user's prompt and, on failure, throw the user's turn away entirely. Ensuring the text protocol for the active model no longer performs blocking inline calibration or throws out of the prompt path under any circumstance; calibration now only ever runs off the hot path, via an explicit `/toolprobe` or the new evidence-gated auto-probe below.
+- A model whose native tool calls keep failing argument validation is now automatically probed and, on graded evidence, escalated: a local/managed model gets an evidence-gated auto-probe (native is tried first; the model is only routed to the text protocol if native genuinely has no working path), and a cloud model escalates to a more capable router tier. This replaces a validation-failure escalation path that previously reused the mutation-blast-radius escape hatch and so treated a read-only tool's repeated validation failures as a no-op.
+- The model router's tier resolution and configured-model lookup now honor a persisted "no working tool-call path" probe verdict for local/managed models: a medium-tier turn falls back to the expensive tier (or the model is skipped) instead of routing to a model already proven unable to call tools.
+- A buffered cheap-tier routed turn that throws now rolls the live in-memory session state back to match what was actually persisted, instead of leaving never-flushed messages permanently stranded in memory.
+- Native tool-call probe trials and text-protocol calibration completions now count toward the turn-scoped cost guard and daily usage totals (were previously untracked — up to ~10 free completions on a model's first probe).
+- A text-protocol model that repeatedly emits unparseable prose instead of a tool call now receives an in-loop corrective reminder (throttled after the first firing), closing a gap where the existing runaway/stall backstop only trips on repeated *parsed* tool-call signatures.
+- A dead tmux session whose job never reached a terminal state now releases its bound managed lane (one report per non-terminal agent, `reasonCode: "tmux_session_orphaned"`) during session-start reconcile, so a goal bound to it stops waiting on a worker that can no longer report back; nothing is killed, only the lane record is released.
+- A goal waiting on a dispatched worker now escalates to the owner (`action: "ask-user"`, reason `worker_wait_timeout`) after a bounded max-wait (default 60 minutes) instead of waiting indefinitely, when the worker is alive but hung past its deadline; every pre-existing caller that omits the new optional wait-clock arguments behaves byte-identically (waits indefinitely, as before).
+- A managed (tmux) worker's terminal usage claim now attributes to its lane's advisory `costUsd`, closing the previously-documented undercount in a goal's `continuationWorkerSpendUsd` for tmux-worker spend.
+- A goal requirement bound to a worker lane that vanished after `/reload` (a genuinely-running managed lane is never snapshotted at dispatch time) is no longer at risk of a duplicate re-dispatch: `dispatch_worker` now refuses re-dispatch when the bound lane's liveness/outcome cannot be determined (`bound_lane_indeterminate`) or is still live (`requirement_already_bound`), preserving the existing binding unchanged; a bound lane with a confirmed terminal outcome still allows a legitimate retry.
+- Hardened worktree synchronization with token-bound lock ownership, lifecycle serialization, exact gated-tip landing, crash-recovery reconciliation, cumulative overlap checks, and typed lane Git/check actions; hard lane workers no longer expose unrestricted `bash`.
+- Fixed concurrent atomic writes by giving each invocation an exclusive same-directory temporary file and cleaning up only its own temporary path.
+
+### Performance
+
+- Memoized per-message context-audit and token-estimate work within a session (object-identity keyed), byte-identical vs full recompute across compaction and branch-switch boundaries — the full-history rescan no longer reruns on every tool-call round trip.
+- Precompiled and cached minimatch patterns for resource-profile filtering (~8% of startup CPU; refired on every reload/profile switch before).
+- Extension TS transforms cached in a durable `agentDir/cache/jiti-transforms` directory (jiti's content-hash fsCache made explicit; hot-reload module isolation preserved).
+- Lazy highlight.js: `lib/core` + register-on-first-use (~190 eager grammar registrations removed from startup), identical output/alias resolution.
+- Cached resolved `fd`/`rg` system-PATH locations across runs (no `spawnSync` probe per launch; staleness re-probes).
+
+### Tests
+
+- Pinned the transform-before-cost-guard pipeline-order invariant (regression test fails under a simulated inverted order).
+- Added a permanent regression guard proving goal/task state resolution survives compaction whose cut point lands past the latest snapshot, in-memory and after a session-file reload (investigated as a suspected bug; the repro passed, so no source change was needed).
+
 ## [0.81.38] - 2026-07-16
 
 ### Changed

package/README.md

@@ -323,6 +323,8 @@ Pi has two separate startup features:
 
 Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
 
+Runtime orchestration, recovery, and learning telemetry stays local. See [docs/telemetry.md](docs/telemetry.md) for its trust boundaries, locations, and retention rules.
+
 ---
 
 ## Context Files

package/dist/bundled-resources/extensions/tmux-agent-manager/README.md

@@ -20,9 +20,16 @@ Important actions:
 - `workspace_plan` — dry-run a tmux session/pane layout.
 - `launch_workspace` — launch panes immediately; pass `dryRun:true` only when a preview is useful.
 - `fire_task` — open provider CLIs in tmux panes, inject prompts, stream pane output through event-driven DONE/BLOCKED watchers, write result files, and wake the parent with a bounded terminal handoff.
+- `send_followup` — re-inject a fresh prompt into an already-live job's pane (default: primary agent; `agentId` targets another) without relaunching. Re-arms the completion watcher for a new turn with a unique per-turn marker pair and reuses the same event-driven handoff.
+- `dismiss` — stop tracking a job (no more re-arming/handoffs) without killing its tmux session; the pane keeps running.
 - `job_status`, `list_jobs`, `set_variable`, `list_variables` — inspect and steer managed jobs.
 - `stop_job`, `stop_session` — dry-run/confirmed tmux cleanup.
 - `notify`, `set_status`, `clear_status` — tmux UI/status metadata.
+- `grant_dispatch`, `revoke_grant` — create/end a standing approval grant that lets `fire_task`/`send_followup` dispatch unattended within its bounds (agent, budget, optional goal/tool/path scope). See Safety below.
+
+At session start, live tmux sessions are reconciled against this session's own job records: a session
+that vanished while its job was not yet terminal is marked orphaned (informational only, nothing is
+killed); a session that is still alive with a pending turn has its watcher re-armed.
 
 ## Built-in team templates
 
@@ -60,7 +67,17 @@ tmux_agent_manager({
 
 ## Safety
 
-Launch actions type commands into tmux panes and execute provider CLIs without an extra approval dialog. Use `dryRun:true` when the task or provider choice is still ambiguous. Stop actions are destructive to running pane work, so they remain previews by default and require `confirm:"yes-tmux-stop"` for real cleanup.
+A real (non-`dryRun`) `fire_task`/`send_followup` launch is approval-gated: it requires either a
+standing grant (`grant_dispatch` — interactively confirmed, or authorized via the `--allow-tmux-dispatch`
+flag when no UI is attached) or a one-shot interactive approval. With neither available, the launch is
+refused, never silent. A grant-covered `pi` child launches with a restricted profile (`--tools`/
+`--resource-profile` or `--no-extensions --no-skills`, plus a scoped `--append-system-prompt` naming the
+grant and its hard stops) pushed into the child's own launch configuration — this is not an in-process
+sandbox, and non-`pi` agents are bounded only at the launch layer; their internal tool-loop behavior is
+that CLI's own responsibility. Grant budget (`maxLaunches`, expiry) is enforced; any advisory USD figure
+or self-reported worker usage is a claim to review, never a hard cross-process cap.
+
+Use `dryRun:true` when the task or provider choice is still ambiguous. Stop actions are destructive to running pane work, so they remain previews by default and require `confirm:"yes-tmux-stop"` for real cleanup.
 
 The tool refuses existing tmux sessions. Existing job directories are refused unless `force:true`, which archives the old job directory under `~/.pi/agent/work/background/tmux-agent-manager/state/archives` before launching.
 

package/dist/bundled-resources/extensions/tmux-agent-manager/dispatch-grant.d.ts

@@ -0,0 +1,133 @@
+import type { Usage } from "@caupulican/pi-ai";
+/**
+ * The STANDING GRANT for approval-gated tmux dispatch (owner authorizes once via `grant_dispatch`;
+ * the extension then dispatches unattended WITHIN the grant's bounds). Pure data + pure decode/decision
+ * logic only — no session/tmux/filesystem access, so every function here is directly unit-testable.
+ * The extension (index.ts) owns reading/writing session custom entries and calls into this module for
+ * decoding and authorization decisions.
+ *
+ * HONEST TRUST BOUNDARY: this grant bounds WHO may be launched, HOW OFTEN, and WITH WHAT launch-time
+ * envelope (pushed into the child's own CLI flags) — it never claims to gate the child's in-process
+ * tool loop, which is a separate OS process outside this runtime's `beforeToolCall` machinery.
+ */
+export type Provider = "pi" | "codex" | "agy" | "claude" | "opencode" | "custom";
+export declare const GRANT_CUSTOM_TYPE = "tmux-dispatch-grant";
+export declare const GRANT_USAGE_CUSTOM_TYPE = "tmux-dispatch-grant-usage";
+export interface TmuxDispatchGrantEnvelope {
+    allowedTools?: string[];
+    resourceProfile?: string;
+    writePaths?: string[];
+}
+export interface TmuxDispatchGrantBudget {
+    maxLaunches: number;
+    maxWallClockMs?: number;
+    maxUsdAdvisory?: number;
+}
+export interface TmuxDispatchGrant {
+    grantId: string;
+    createdAt: string;
+    agent: Provider;
+    scope: {
+        goalId?: string;
+    };
+    envelope: TmuxDispatchGrantEnvelope;
+    budget: TmuxDispatchGrantBudget;
+    expiresAt?: string;
+}
+/** Appended by `revoke_grant`. Shares `GRANT_CUSTOM_TYPE` so the SAME latest-on-branch read that
+ * resolves an active grant also sees a revocation and stops treating any older grant beneath it as
+ * active — a tombstone is a hard stop, never skipped over to resurrect an earlier grant. */
+export interface TmuxDispatchGrantTombstone {
+    tombstone: true;
+    grantId: string;
+    revokedAt: string;
+}
+export interface TmuxDispatchGrantUsage {
+    grantId: string;
+    jobId: string;
+    at: string;
+}
+export declare function isTmuxDispatchGrantTombstone(value: unknown): value is TmuxDispatchGrantTombstone;
+export declare function isTmuxDispatchGrant(value: unknown): value is TmuxDispatchGrant;
+export declare function isTmuxDispatchGrantUsage(value: unknown): value is TmuxDispatchGrantUsage;
+export declare function makeGrantId(): string;
+export interface GrantCoverageRequest {
+    agent: Provider;
+    goalId?: string;
+    nowIso?: string;
+}
+/** Whether `grant` authorizes a launch for `request`: same agent, goal-scope match (an UNSCOPED grant
+ * covers any goal including none; a goal-SCOPED grant covers ONLY that exact goalId), and the grant is
+ * not past `expiresAt`. Budget (maxLaunches) is checked separately via {@link isGrantBudgetExhausted}
+ * because counting usages requires the caller's session-entry access. */
+export declare function grantCovers(grant: TmuxDispatchGrant, request: GrantCoverageRequest): boolean;
+/** Count spend entries for `grantId` among already-decoded custom-entry payloads (the caller walks the
+ * session branch and passes the raw `data` values — this stays pure/session-agnostic). */
+export declare function countGrantUsages(grantId: string, usageEntries: readonly unknown[]): number;
+export declare function isGrantBudgetExhausted(grant: TmuxDispatchGrant, usedCount: number): boolean;
+export declare function buildGrantUsageEntry(grantId: string, jobId: string, nowIso?: string): TmuxDispatchGrantUsage;
+export declare function buildTombstone(grantId: string, nowIso?: string): TmuxDispatchGrantTombstone;
+export interface GrantDispatchParams {
+    agent: Provider;
+    goalId?: string;
+    allowedTools?: string[];
+    resourceProfile?: string;
+    writePaths?: string[];
+    maxLaunches: number;
+    expiresInMinutes?: number;
+    maxUsdAdvisory?: number;
+}
+/** Build a new grant record from `grant_dispatch` params. Pure — the caller (index.ts) owns the
+ * approval gate (ui.confirm / opt-in flag) and the `pi.appendEntry` persistence; this only shapes the
+ * data, so it stays independently testable and never itself decides whether creation is authorized. */
+export declare function buildGrant(params: GrantDispatchParams, nowIso?: string): TmuxDispatchGrant;
+export declare function describeGrant(grant: TmuxDispatchGrant): string;
+export declare const DEFAULT_READ_BIASED_TOOLS: readonly string[];
+export interface LaunchProfileSource {
+    /** Human-readable identity for the scoped system prompt (e.g. "grant <id>" or a one-shot label). */
+    identity: string;
+    allowedTools?: string[];
+    resourceProfile?: string;
+    writePaths?: string[];
+    /**
+     * Worktree-sync lane key this launch is bound to (per-agent -- see `applyLaunchProfile`'s caller,
+     * which builds a per-agent `LaunchProfileSource` only when that agent carries `worktreeLane`).
+     * When present, `buildLaunchProfileFlags` appends `--worktree-lane <key>` (the same CLI flag
+     * `src/cli/args.ts` already exposes, sugar over the `PI_WORKTREE_LANE` env contract) and
+     * `buildScopedSystemPrompt` appends one lane-doctrine sentence.
+     */
+    worktreeLane?: string;
+    /**
+     * Process-matrix parent identity for this launch (see `core/process-matrix/runtime.ts`): the
+     * dispatching process's own pid/sessionId. When present, `buildLaunchProfileFlags` appends
+     * `--parent-pid`/`--parent-session` (sugar over `PI_PARENT_PID`/`PI_PARENT_SESSION`) so the
+     * child self-registers as a worker of this session and winds down gracefully if it disappears.
+     */
+    parentPid?: number;
+    parentSession?: string;
+    /** Stable goal/task identity used to fence process-matrix recovery. */
+    taskRef?: string;
+}
+/** A grant-covered launch derives its profile from the grant's envelope. */
+export declare function launchProfileSourceFromGrant(grant: TmuxDispatchGrant): LaunchProfileSource;
+/** A one-shot interactively-approved launch (no standing grant) still gets the conservative default
+ * profile — approving a single launch is not the same as defining an unrestricted envelope. */
+export declare const ONE_SHOT_LAUNCH_PROFILE_SOURCE: LaunchProfileSource;
+export interface LaunchProfileFlag {
+    flag: string;
+    value?: string;
+}
+/** Build the CLI flags to append to a child `pi` invocation so the grant's envelope lives in the
+ * child's OWN launch config (verified flag names: --tools, --resource-profile, --no-extensions,
+ * --no-skills, --append-system-prompt). Never includes --no-approve: the child must keep gating its
+ * own hard stops. */
+export declare function buildLaunchProfileFlags(source: LaunchProfileSource): LaunchProfileFlag[];
+export declare function buildScopedSystemPrompt(source: LaunchProfileSource): string;
+/** Permissively decode a worker-reported usage CLAIM (a cooperative worker may write this to a
+ * well-known sibling file before printing its completion marker). Read-defensive: missing/malformed
+ * numeric fields default to 0 rather than throwing — this is untrusted, OPTIONAL, advisory input, never
+ * an authoritative billing record. Returns undefined only when `raw` isn't even an object, so the
+ * caller can distinguish "no claim offered" (skip reporting) from "a claim was offered" (report it,
+ * however partial). */
+export declare function decodeTmuxWorkerUsageClaim(raw: unknown): Usage | undefined;
+//# sourceMappingURL=dispatch-grant.d.ts.map

package/dist/bundled-resources/extensions/tmux-agent-manager/dispatch-grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-grant.d.ts","sourceRoot":"","sources":["../../../../src/bundled-resources/extensions/tmux-agent-manager/dispatch-grant.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEjF,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AACvD,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,MAAM,WAAW,yBAAyB;IACzC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,QAAQ,EAAE,yBAAyB,CAAC;IACpC,MAAM,EAAE,uBAAuB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;8FAE4F;AAC5F,MAAM,WAAW,0BAA0B;IAC1C,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACX;AAYD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAGhG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAM9E;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAGxF;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;yEAGyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAS5F;AAED;4FAC0F;AAC1F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAI1F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3F;AAED,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,SAA2B,GAC/B,sBAAsB,CAExB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,SAA2B,GAAG,0BAA0B,CAE7G;AAED,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;uGAEuG;AACvG,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,SAA2B,GAAG,iBAAiB,CAuB5G;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAsB9D;AAMD,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAAmC,CAAC;AAE3F,MAAM,WAAW,mBAAmB;IACnC,oGAAoG;IACpG,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,4EAA4E;AAC5E,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,iBAAiB,GAAG,mBAAmB,CAO1F;AAED;iGAC+F;AAC/F,eAAO,MAAM,8BAA8B,EAAE,mBAE5C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;qBAGqB;AACrB,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,EAAE,CAWxF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAa3E;AAMD;;;;;uBAKuB;AACvB,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAkB1E","sourcesContent":["import * as crypto from \"node:crypto\";\nimport type { Usage } from \"@caupulican/pi-ai\";\n\n/**\n * The STANDING GRANT for approval-gated tmux dispatch (owner authorizes once via `grant_dispatch`;\n * the extension then dispatches unattended WITHIN the grant's bounds). Pure data + pure decode/decision\n * logic only — no session/tmux/filesystem access, so every function here is directly unit-testable.\n * The extension (index.ts) owns reading/writing session custom entries and calls into this module for\n * decoding and authorization decisions.\n *\n * HONEST TRUST BOUNDARY: this grant bounds WHO may be launched, HOW OFTEN, and WITH WHAT launch-time\n * envelope (pushed into the child's own CLI flags) — it never claims to gate the child's in-process\n * tool loop, which is a separate OS process outside this runtime's `beforeToolCall` machinery.\n */\n\nexport type Provider = \"pi\" | \"codex\" | \"agy\" | \"claude\" | \"opencode\" | \"custom\";\n\nexport const GRANT_CUSTOM_TYPE = \"tmux-dispatch-grant\";\nexport const GRANT_USAGE_CUSTOM_TYPE = \"tmux-dispatch-grant-usage\";\n\nexport interface TmuxDispatchGrantEnvelope {\n\tallowedTools?: string[];\n\tresourceProfile?: string;\n\twritePaths?: string[];\n}\n\nexport interface TmuxDispatchGrantBudget {\n\tmaxLaunches: number;\n\tmaxWallClockMs?: number;\n\tmaxUsdAdvisory?: number;\n}\n\nexport interface TmuxDispatchGrant {\n\tgrantId: string;\n\tcreatedAt: string;\n\tagent: Provider;\n\tscope: { goalId?: string };\n\tenvelope: TmuxDispatchGrantEnvelope;\n\tbudget: TmuxDispatchGrantBudget;\n\texpiresAt?: string;\n}\n\n/** Appended by `revoke_grant`. Shares `GRANT_CUSTOM_TYPE` so the SAME latest-on-branch read that\n * resolves an active grant also sees a revocation and stops treating any older grant beneath it as\n * active — a tombstone is a hard stop, never skipped over to resurrect an earlier grant. */\nexport interface TmuxDispatchGrantTombstone {\n\ttombstone: true;\n\tgrantId: string;\n\trevokedAt: string;\n}\n\nexport interface TmuxDispatchGrantUsage {\n\tgrantId: string;\n\tjobId: string;\n\tat: string;\n}\n\nconst PROVIDERS: readonly Provider[] = [\"pi\", \"codex\", \"agy\", \"claude\", \"opencode\", \"custom\"];\n\nfunction isProvider(value: unknown): value is Provider {\n\treturn typeof value === \"string\" && (PROVIDERS as readonly string[]).includes(value);\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nexport function isTmuxDispatchGrantTombstone(value: unknown): value is TmuxDispatchGrantTombstone {\n\tif (!isPlainRecord(value)) return false;\n\treturn value.tombstone === true && typeof value.grantId === \"string\" && typeof value.revokedAt === \"string\";\n}\n\nexport function isTmuxDispatchGrant(value: unknown): value is TmuxDispatchGrant {\n\tif (!isPlainRecord(value) || value.tombstone === true) return false;\n\tif (typeof value.grantId !== \"string\" || typeof value.createdAt !== \"string\" || !isProvider(value.agent))\n\t\treturn false;\n\tif (!isPlainRecord(value.scope) || !isPlainRecord(value.envelope) || !isPlainRecord(value.budget)) return false;\n\treturn typeof value.budget.maxLaunches === \"number\" && Number.isFinite(value.budget.maxLaunches);\n}\n\nexport function isTmuxDispatchGrantUsage(value: unknown): value is TmuxDispatchGrantUsage {\n\tif (!isPlainRecord(value)) return false;\n\treturn typeof value.grantId === \"string\" && typeof value.jobId === \"string\" && typeof value.at === \"string\";\n}\n\nexport function makeGrantId(): string {\n\treturn `grant-${Date.now().toString(36)}-${crypto.randomBytes(4).toString(\"hex\")}`;\n}\n\nexport interface GrantCoverageRequest {\n\tagent: Provider;\n\tgoalId?: string;\n\tnowIso?: string;\n}\n\n/** Whether `grant` authorizes a launch for `request`: same agent, goal-scope match (an UNSCOPED grant\n * covers any goal including none; a goal-SCOPED grant covers ONLY that exact goalId), and the grant is\n * not past `expiresAt`. Budget (maxLaunches) is checked separately via {@link isGrantBudgetExhausted}\n * because counting usages requires the caller's session-entry access. */\nexport function grantCovers(grant: TmuxDispatchGrant, request: GrantCoverageRequest): boolean {\n\tif (grant.agent !== request.agent) return false;\n\tif (grant.scope.goalId && grant.scope.goalId !== request.goalId) return false;\n\tif (grant.expiresAt) {\n\t\tconst now = Date.parse(request.nowIso ?? new Date().toISOString());\n\t\tconst expiry = Date.parse(grant.expiresAt);\n\t\tif (Number.isFinite(expiry) && Number.isFinite(now) && now >= expiry) return false;\n\t}\n\treturn true;\n}\n\n/** Count spend entries for `grantId` among already-decoded custom-entry payloads (the caller walks the\n * session branch and passes the raw `data` values — this stays pure/session-agnostic). */\nexport function countGrantUsages(grantId: string, usageEntries: readonly unknown[]): number {\n\tlet count = 0;\n\tfor (const entry of usageEntries) if (isTmuxDispatchGrantUsage(entry) && entry.grantId === grantId) count++;\n\treturn count;\n}\n\nexport function isGrantBudgetExhausted(grant: TmuxDispatchGrant, usedCount: number): boolean {\n\treturn usedCount >= grant.budget.maxLaunches;\n}\n\nexport function buildGrantUsageEntry(\n\tgrantId: string,\n\tjobId: string,\n\tnowIso = new Date().toISOString(),\n): TmuxDispatchGrantUsage {\n\treturn { grantId, jobId, at: nowIso };\n}\n\nexport function buildTombstone(grantId: string, nowIso = new Date().toISOString()): TmuxDispatchGrantTombstone {\n\treturn { tombstone: true, grantId, revokedAt: nowIso };\n}\n\nexport interface GrantDispatchParams {\n\tagent: Provider;\n\tgoalId?: string;\n\tallowedTools?: string[];\n\tresourceProfile?: string;\n\twritePaths?: string[];\n\tmaxLaunches: number;\n\texpiresInMinutes?: number;\n\tmaxUsdAdvisory?: number;\n}\n\n/** Build a new grant record from `grant_dispatch` params. Pure — the caller (index.ts) owns the\n * approval gate (ui.confirm / opt-in flag) and the `pi.appendEntry` persistence; this only shapes the\n * data, so it stays independently testable and never itself decides whether creation is authorized. */\nexport function buildGrant(params: GrantDispatchParams, nowIso = new Date().toISOString()): TmuxDispatchGrant {\n\tif (!Number.isFinite(params.maxLaunches) || params.maxLaunches < 1)\n\t\tthrow new Error(\"grant_dispatch requires maxLaunches >= 1\");\n\tconst expiresAt =\n\t\tparams.expiresInMinutes !== undefined\n\t\t\t? new Date(Date.parse(nowIso) + Math.max(1, params.expiresInMinutes) * 60_000).toISOString()\n\t\t\t: undefined;\n\treturn {\n\t\tgrantId: makeGrantId(),\n\t\tcreatedAt: nowIso,\n\t\tagent: params.agent,\n\t\tscope: { goalId: params.goalId },\n\t\tenvelope: {\n\t\t\tallowedTools: params.allowedTools,\n\t\t\tresourceProfile: params.resourceProfile,\n\t\t\twritePaths: params.writePaths,\n\t\t},\n\t\tbudget: {\n\t\t\tmaxLaunches: Math.trunc(params.maxLaunches),\n\t\t\tmaxUsdAdvisory: params.maxUsdAdvisory,\n\t\t},\n\t\texpiresAt,\n\t};\n}\n\nexport function describeGrant(grant: TmuxDispatchGrant): string {\n\treturn [\n\t\t`Grant id: ${grant.grantId}`,\n\t\t`Agent: ${grant.agent}`,\n\t\tgrant.scope.goalId ? `Goal scope: ${grant.scope.goalId}` : \"Goal scope: none (covers any goal)\",\n\t\t`Max launches: ${grant.budget.maxLaunches}`,\n\t\tgrant.expiresAt ? `Expires: ${grant.expiresAt}` : \"Expires: never (until revoke_grant)\",\n\t\tgrant.envelope.allowedTools?.length\n\t\t\t? `Allowed tools: ${grant.envelope.allowedTools.join(\", \")}`\n\t\t\t: `Allowed tools: read-biased safe default (${DEFAULT_READ_BIASED_TOOLS.join(\", \")})`,\n\t\tgrant.envelope.resourceProfile\n\t\t\t? `Resource profile: ${grant.envelope.resourceProfile}`\n\t\t\t: \"Resource profile: none (child launches with --no-extensions --no-skills)\",\n\t\tgrant.envelope.writePaths?.length\n\t\t\t? `Write paths: ${grant.envelope.writePaths.join(\", \")}`\n\t\t\t: \"Write paths: none declared\",\n\t\tgrant.budget.maxUsdAdvisory !== undefined\n\t\t\t? `Advisory USD cap: ${grant.budget.maxUsdAdvisory} (not enforced across the process boundary — advisory only)`\n\t\t\t: undefined,\n\t]\n\t\t.filter((line): line is string => Boolean(line))\n\t\t.join(\"\\n\");\n}\n\n// ---------------------------------------------------------------------------\n// Launch-profile flags: the REAL lever — pushed into the child `pi` CLI's own config.\n// ---------------------------------------------------------------------------\n\nexport const DEFAULT_READ_BIASED_TOOLS: readonly string[] = [\"read\", \"grep\", \"find\", \"ls\"];\n\nexport interface LaunchProfileSource {\n\t/** Human-readable identity for the scoped system prompt (e.g. \"grant <id>\" or a one-shot label). */\n\tidentity: string;\n\tallowedTools?: string[];\n\tresourceProfile?: string;\n\twritePaths?: string[];\n\t/**\n\t * Worktree-sync lane key this launch is bound to (per-agent -- see `applyLaunchProfile`'s caller,\n\t * which builds a per-agent `LaunchProfileSource` only when that agent carries `worktreeLane`).\n\t * When present, `buildLaunchProfileFlags` appends `--worktree-lane <key>` (the same CLI flag\n\t * `src/cli/args.ts` already exposes, sugar over the `PI_WORKTREE_LANE` env contract) and\n\t * `buildScopedSystemPrompt` appends one lane-doctrine sentence.\n\t */\n\tworktreeLane?: string;\n\t/**\n\t * Process-matrix parent identity for this launch (see `core/process-matrix/runtime.ts`): the\n\t * dispatching process's own pid/sessionId. When present, `buildLaunchProfileFlags` appends\n\t * `--parent-pid`/`--parent-session` (sugar over `PI_PARENT_PID`/`PI_PARENT_SESSION`) so the\n\t * child self-registers as a worker of this session and winds down gracefully if it disappears.\n\t */\n\tparentPid?: number;\n\tparentSession?: string;\n\t/** Stable goal/task identity used to fence process-matrix recovery. */\n\ttaskRef?: string;\n}\n\n/** A grant-covered launch derives its profile from the grant's envelope. */\nexport function launchProfileSourceFromGrant(grant: TmuxDispatchGrant): LaunchProfileSource {\n\treturn {\n\t\tidentity: `grant ${grant.grantId}`,\n\t\tallowedTools: grant.envelope.allowedTools,\n\t\tresourceProfile: grant.envelope.resourceProfile,\n\t\twritePaths: grant.envelope.writePaths,\n\t};\n}\n\n/** A one-shot interactively-approved launch (no standing grant) still gets the conservative default\n * profile — approving a single launch is not the same as defining an unrestricted envelope. */\nexport const ONE_SHOT_LAUNCH_PROFILE_SOURCE: LaunchProfileSource = {\n\tidentity: \"a one-shot owner-approved tmux dispatch (no standing grant)\",\n};\n\nexport interface LaunchProfileFlag {\n\tflag: string;\n\tvalue?: string;\n}\n\n/** Build the CLI flags to append to a child `pi` invocation so the grant's envelope lives in the\n * child's OWN launch config (verified flag names: --tools, --resource-profile, --no-extensions,\n * --no-skills, --append-system-prompt). Never includes --no-approve: the child must keep gating its\n * own hard stops. */\nexport function buildLaunchProfileFlags(source: LaunchProfileSource): LaunchProfileFlag[] {\n\tconst tools = source.allowedTools?.length ? source.allowedTools : DEFAULT_READ_BIASED_TOOLS;\n\tconst flags: LaunchProfileFlag[] = [{ flag: \"--tools\", value: tools.join(\",\") }];\n\tif (source.resourceProfile) flags.push({ flag: \"--resource-profile\", value: source.resourceProfile });\n\telse flags.push({ flag: \"--no-extensions\" }, { flag: \"--no-skills\" });\n\tif (source.worktreeLane) flags.push({ flag: \"--worktree-lane\", value: source.worktreeLane });\n\tif (source.parentPid !== undefined) flags.push({ flag: \"--parent-pid\", value: String(source.parentPid) });\n\tif (source.parentSession) flags.push({ flag: \"--parent-session\", value: source.parentSession });\n\tif (source.taskRef) flags.push({ flag: \"--task-ref\", value: source.taskRef });\n\tflags.push({ flag: \"--append-system-prompt\", value: buildScopedSystemPrompt(source) });\n\treturn flags;\n}\n\nexport function buildScopedSystemPrompt(source: LaunchProfileSource): string {\n\tconst paths = source.writePaths?.length ? source.writePaths.join(\", \") : \"no additional paths granted\";\n\tconst sentences = [\n\t\t`You are a tmux worker dispatched under ${source.identity}.`,\n\t\t`Stay within these write paths: ${paths}.`,\n\t\t\"Hard stops — publishing/npm, git push, tagging a release, changing credentials/auth, or destructive deletion — require returning BLOCKED for owner approval. Never self-approve a hard stop.\",\n\t];\n\tif (source.worktreeLane) {\n\t\tsentences.push(\n\t\t\t`You are bound to worktree-sync lane '${source.worktreeLane}': work only inside this lane's own worktree, integrate exclusively via worktree_sync land, and never touch main directly.`,\n\t\t);\n\t}\n\treturn sentences.join(\" \");\n}\n\n// ---------------------------------------------------------------------------\n// Advisory worker usage claim: budget stays advisory across the process boundary.\n// ---------------------------------------------------------------------------\n\n/** Permissively decode a worker-reported usage CLAIM (a cooperative worker may write this to a\n * well-known sibling file before printing its completion marker). Read-defensive: missing/malformed\n * numeric fields default to 0 rather than throwing — this is untrusted, OPTIONAL, advisory input, never\n * an authoritative billing record. Returns undefined only when `raw` isn't even an object, so the\n * caller can distinguish \"no claim offered\" (skip reporting) from \"a claim was offered\" (report it,\n * however partial). */\nexport function decodeTmuxWorkerUsageClaim(raw: unknown): Usage | undefined {\n\tif (!isPlainRecord(raw)) return undefined;\n\tconst num = (value: unknown): number => (typeof value === \"number\" && Number.isFinite(value) ? value : 0);\n\tconst cost = isPlainRecord(raw.cost) ? raw.cost : {};\n\treturn {\n\t\tinput: num(raw.input),\n\t\toutput: num(raw.output),\n\t\tcacheRead: num(raw.cacheRead),\n\t\tcacheWrite: num(raw.cacheWrite),\n\t\ttotalTokens: num(raw.totalTokens),\n\t\tcost: {\n\t\t\tinput: num(cost.input),\n\t\t\toutput: num(cost.output),\n\t\t\tcacheRead: num(cost.cacheRead),\n\t\t\tcacheWrite: num(cost.cacheWrite),\n\t\t\ttotal: num(cost.total),\n\t\t},\n\t};\n}\n"]}

package/dist/bundled-resources/extensions/tmux-agent-manager/dispatch-grant.js

@@ -0,0 +1,198 @@
+import * as crypto from "node:crypto";
+export const GRANT_CUSTOM_TYPE = "tmux-dispatch-grant";
+export const GRANT_USAGE_CUSTOM_TYPE = "tmux-dispatch-grant-usage";
+const PROVIDERS = ["pi", "codex", "agy", "claude", "opencode", "custom"];
+function isProvider(value) {
+    return typeof value === "string" && PROVIDERS.includes(value);
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isTmuxDispatchGrantTombstone(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return value.tombstone === true && typeof value.grantId === "string" && typeof value.revokedAt === "string";
+}
+export function isTmuxDispatchGrant(value) {
+    if (!isPlainRecord(value) || value.tombstone === true)
+        return false;
+    if (typeof value.grantId !== "string" || typeof value.createdAt !== "string" || !isProvider(value.agent))
+        return false;
+    if (!isPlainRecord(value.scope) || !isPlainRecord(value.envelope) || !isPlainRecord(value.budget))
+        return false;
+    return typeof value.budget.maxLaunches === "number" && Number.isFinite(value.budget.maxLaunches);
+}
+export function isTmuxDispatchGrantUsage(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return typeof value.grantId === "string" && typeof value.jobId === "string" && typeof value.at === "string";
+}
+export function makeGrantId() {
+    return `grant-${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+}
+/** Whether `grant` authorizes a launch for `request`: same agent, goal-scope match (an UNSCOPED grant
+ * covers any goal including none; a goal-SCOPED grant covers ONLY that exact goalId), and the grant is
+ * not past `expiresAt`. Budget (maxLaunches) is checked separately via {@link isGrantBudgetExhausted}
+ * because counting usages requires the caller's session-entry access. */
+export function grantCovers(grant, request) {
+    if (grant.agent !== request.agent)
+        return false;
+    if (grant.scope.goalId && grant.scope.goalId !== request.goalId)
+        return false;
+    if (grant.expiresAt) {
+        const now = Date.parse(request.nowIso ?? new Date().toISOString());
+        const expiry = Date.parse(grant.expiresAt);
+        if (Number.isFinite(expiry) && Number.isFinite(now) && now >= expiry)
+            return false;
+    }
+    return true;
+}
+/** Count spend entries for `grantId` among already-decoded custom-entry payloads (the caller walks the
+ * session branch and passes the raw `data` values — this stays pure/session-agnostic). */
+export function countGrantUsages(grantId, usageEntries) {
+    let count = 0;
+    for (const entry of usageEntries)
+        if (isTmuxDispatchGrantUsage(entry) && entry.grantId === grantId)
+            count++;
+    return count;
+}
+export function isGrantBudgetExhausted(grant, usedCount) {
+    return usedCount >= grant.budget.maxLaunches;
+}
+export function buildGrantUsageEntry(grantId, jobId, nowIso = new Date().toISOString()) {
+    return { grantId, jobId, at: nowIso };
+}
+export function buildTombstone(grantId, nowIso = new Date().toISOString()) {
+    return { tombstone: true, grantId, revokedAt: nowIso };
+}
+/** Build a new grant record from `grant_dispatch` params. Pure — the caller (index.ts) owns the
+ * approval gate (ui.confirm / opt-in flag) and the `pi.appendEntry` persistence; this only shapes the
+ * data, so it stays independently testable and never itself decides whether creation is authorized. */
+export function buildGrant(params, nowIso = new Date().toISOString()) {
+    if (!Number.isFinite(params.maxLaunches) || params.maxLaunches < 1)
+        throw new Error("grant_dispatch requires maxLaunches >= 1");
+    const expiresAt = params.expiresInMinutes !== undefined
+        ? new Date(Date.parse(nowIso) + Math.max(1, params.expiresInMinutes) * 60_000).toISOString()
+        : undefined;
+    return {
+        grantId: makeGrantId(),
+        createdAt: nowIso,
+        agent: params.agent,
+        scope: { goalId: params.goalId },
+        envelope: {
+            allowedTools: params.allowedTools,
+            resourceProfile: params.resourceProfile,
+            writePaths: params.writePaths,
+        },
+        budget: {
+            maxLaunches: Math.trunc(params.maxLaunches),
+            maxUsdAdvisory: params.maxUsdAdvisory,
+        },
+        expiresAt,
+    };
+}
+export function describeGrant(grant) {
+    return [
+        `Grant id: ${grant.grantId}`,
+        `Agent: ${grant.agent}`,
+        grant.scope.goalId ? `Goal scope: ${grant.scope.goalId}` : "Goal scope: none (covers any goal)",
+        `Max launches: ${grant.budget.maxLaunches}`,
+        grant.expiresAt ? `Expires: ${grant.expiresAt}` : "Expires: never (until revoke_grant)",
+        grant.envelope.allowedTools?.length
+            ? `Allowed tools: ${grant.envelope.allowedTools.join(", ")}`
+            : `Allowed tools: read-biased safe default (${DEFAULT_READ_BIASED_TOOLS.join(", ")})`,
+        grant.envelope.resourceProfile
+            ? `Resource profile: ${grant.envelope.resourceProfile}`
+            : "Resource profile: none (child launches with --no-extensions --no-skills)",
+        grant.envelope.writePaths?.length
+            ? `Write paths: ${grant.envelope.writePaths.join(", ")}`
+            : "Write paths: none declared",
+        grant.budget.maxUsdAdvisory !== undefined
+            ? `Advisory USD cap: ${grant.budget.maxUsdAdvisory} (not enforced across the process boundary — advisory only)`
+            : undefined,
+    ]
+        .filter((line) => Boolean(line))
+        .join("\n");
+}
+// ---------------------------------------------------------------------------
+// Launch-profile flags: the REAL lever — pushed into the child `pi` CLI's own config.
+// ---------------------------------------------------------------------------
+export const DEFAULT_READ_BIASED_TOOLS = ["read", "grep", "find", "ls"];
+/** A grant-covered launch derives its profile from the grant's envelope. */
+export function launchProfileSourceFromGrant(grant) {
+    return {
+        identity: `grant ${grant.grantId}`,
+        allowedTools: grant.envelope.allowedTools,
+        resourceProfile: grant.envelope.resourceProfile,
+        writePaths: grant.envelope.writePaths,
+    };
+}
+/** A one-shot interactively-approved launch (no standing grant) still gets the conservative default
+ * profile — approving a single launch is not the same as defining an unrestricted envelope. */
+export const ONE_SHOT_LAUNCH_PROFILE_SOURCE = {
+    identity: "a one-shot owner-approved tmux dispatch (no standing grant)",
+};
+/** Build the CLI flags to append to a child `pi` invocation so the grant's envelope lives in the
+ * child's OWN launch config (verified flag names: --tools, --resource-profile, --no-extensions,
+ * --no-skills, --append-system-prompt). Never includes --no-approve: the child must keep gating its
+ * own hard stops. */
+export function buildLaunchProfileFlags(source) {
+    const tools = source.allowedTools?.length ? source.allowedTools : DEFAULT_READ_BIASED_TOOLS;
+    const flags = [{ flag: "--tools", value: tools.join(",") }];
+    if (source.resourceProfile)
+        flags.push({ flag: "--resource-profile", value: source.resourceProfile });
+    else
+        flags.push({ flag: "--no-extensions" }, { flag: "--no-skills" });
+    if (source.worktreeLane)
+        flags.push({ flag: "--worktree-lane", value: source.worktreeLane });
+    if (source.parentPid !== undefined)
+        flags.push({ flag: "--parent-pid", value: String(source.parentPid) });
+    if (source.parentSession)
+        flags.push({ flag: "--parent-session", value: source.parentSession });
+    if (source.taskRef)
+        flags.push({ flag: "--task-ref", value: source.taskRef });
+    flags.push({ flag: "--append-system-prompt", value: buildScopedSystemPrompt(source) });
+    return flags;
+}
+export function buildScopedSystemPrompt(source) {
+    const paths = source.writePaths?.length ? source.writePaths.join(", ") : "no additional paths granted";
+    const sentences = [
+        `You are a tmux worker dispatched under ${source.identity}.`,
+        `Stay within these write paths: ${paths}.`,
+        "Hard stops — publishing/npm, git push, tagging a release, changing credentials/auth, or destructive deletion — require returning BLOCKED for owner approval. Never self-approve a hard stop.",
+    ];
+    if (source.worktreeLane) {
+        sentences.push(`You are bound to worktree-sync lane '${source.worktreeLane}': work only inside this lane's own worktree, integrate exclusively via worktree_sync land, and never touch main directly.`);
+    }
+    return sentences.join(" ");
+}
+// ---------------------------------------------------------------------------
+// Advisory worker usage claim: budget stays advisory across the process boundary.
+// ---------------------------------------------------------------------------
+/** Permissively decode a worker-reported usage CLAIM (a cooperative worker may write this to a
+ * well-known sibling file before printing its completion marker). Read-defensive: missing/malformed
+ * numeric fields default to 0 rather than throwing — this is untrusted, OPTIONAL, advisory input, never
+ * an authoritative billing record. Returns undefined only when `raw` isn't even an object, so the
+ * caller can distinguish "no claim offered" (skip reporting) from "a claim was offered" (report it,
+ * however partial). */
+export function decodeTmuxWorkerUsageClaim(raw) {
+    if (!isPlainRecord(raw))
+        return undefined;
+    const num = (value) => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+    const cost = isPlainRecord(raw.cost) ? raw.cost : {};
+    return {
+        input: num(raw.input),
+        output: num(raw.output),
+        cacheRead: num(raw.cacheRead),
+        cacheWrite: num(raw.cacheWrite),
+        totalTokens: num(raw.totalTokens),
+        cost: {
+            input: num(cost.input),
+            output: num(cost.output),
+            cacheRead: num(cost.cacheRead),
+            cacheWrite: num(cost.cacheWrite),
+            total: num(cost.total),
+        },
+    };
+}
+//# sourceMappingURL=dispatch-grant.js.map