@lovehlmmm/primekit 1.0.0

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: pk:orchestrate
+description: "Coordinate staged or parallel jobs across live-verified coding-agent runtimes and in-session subagents, using capability- and risk-based routing, worktree-isolated writes, resumable state, capture, safety gates, and independent arbiter review."
+user-invocable: true
+when_to_use: "Invoke when work should be split across multiple headless runtimes or in-session subagents, routed by task capability and risk, isolated where needed, and reviewed before handoff."
+category: dev-tools
+keywords: [orchestrate, headless, multi-agent, internal, subagents, live-routing, model-routing, capability, risk, worktree, resume, parallel, arbiter]
+argument-hint: "<job-spec.yaml | task description | --resume <run-dir>> [--yes] [--internal]"
+license: MIT
+metadata:
+  author: primekit
+  version: "1.5.0"
+---
+
+# Orchestrate
+
+Coordinate headless coding-agent jobs and in-session subagents through a
+staged, captured, resumable workflow. This is a skill-level coordinator, not a
+new `primekit` command or scheduler service.
+
+Runtime and model catalogs drift. Resolve every route from live execution-time
+evidence. Never treat a runtime, provider, model, alias, flag, or agent seen in
+this file or an older report as currently available.
+
+## Inputs
+
+Accepted forms:
+
+```bash
+/pk:orchestrate "research three implementation options and compare them"
+/pk:orchestrate "compare the auth options" --internal
+/pk:orchestrate plans/orchestrate-jobs.yaml
+/pk:orchestrate plans/orchestrate-jobs.yaml --yes
+/pk:orchestrate --resume plans/reports/orchestrate-<timestamp>
+```
+
+Use a YAML job spec for repeatable runs. For a free-form request, create a
+temporary spec at `plans/reports/orchestrate-<timestamp>/jobs.yaml` before
+dispatch.
+
+`--internal` is a routing preference, not a hard mode. It asks the selection
+policy to consider in-session subagents first for jobs without an explicit
+`runtime:`. A job that needs a separately selectable model, stronger enforced
+isolation, or a control the current harness lacks may use a live-verified CLI
+fallback. Never override an explicit runtime, model, or agent pin silently.
+
+## Authority Map
+
+Keep durable facts in one place:
+
+- [model-routing.md](references/model-routing.md) is the **sole route-selection
+  authority**. It owns capability tiers, risk tiers, task defaults, internal
+  selection, fallback qualification, and model-family independence.
+- [runtime-matrix.md](references/runtime-matrix.md) owns live candidate
+  discovery, probing, command verification, OS evidence, and
+  `<run-dir>/runtimes.json`.
+- [harness-profiles.md](references/harness-profiles.md) owns the evidence schema
+  for permissions, isolation, capture, budgets, and enablement.
+- [internal-routing.md](references/internal-routing.md) owns in-session dispatch,
+  capture, timeout, and resume mechanics.
+- [job-spec.md](references/job-spec.md) owns the YAML schema and execution-state
+  contract.
+
+Do not copy runtime or model catalogs into this file. When references disagree,
+stop and report the contract mismatch.
+
+## Pipeline
+
+### 1. Brainstorm and intake
+
+- Clarify the desired outcome, constraints, non-goals, and acceptance evidence.
+- Read the request or job spec and identify the workspace root.
+- Identify dependencies, destructive or external intent, expected outputs, and
+  runtime constraints.
+- Refuse any plan that would place secrets, tokens, credentials, cookies,
+  private keys, dotenv values, or unrelated private data in prompts or capture.
+- Prefer a direct single-agent workflow when orchestration would add no useful
+  parallelism, staged dependency, runtime diversity, or arbiter value.
+
+### 2. Build the job graph
+
+- Convert the accepted outcome into jobs with explicit `task`, `cwd`, timeout,
+  expected output, and file ownership.
+- Use `depends_on` to form stages.
+- Run same-stage jobs concurrently only when ownership and outputs do not
+  overlap.
+- Mark public-contract, security-sensitive, cross-module, or hard-to-revert
+  implementation as `importance: high`.
+- Set `isolation: worktree` for parallel writers, untrusted write prompts, and
+  any harness whose write boundary is weaker than the job requires.
+- Name the skill or instructions each headless job must load; do not rely on
+  automatic skill discovery in a one-shot process.
+
+### 3. Discover, profile, and route
+
+- Build a live runtime inventory per
+  [runtime-matrix.md](references/runtime-matrix.md).
+- Profile each candidate per
+  [harness-profiles.md](references/harness-profiles.md).
+- Pass the live evidence and job classification to
+  [model-routing.md](references/model-routing.md).
+- Record the selected runtime, model or agent, capability tier, risk tier,
+  controls, evidence source, and fallback reason.
+- A missing, unauthenticated, unverified, or insufficiently controlled
+  candidate cannot satisfy a route.
+- Re-profile fallbacks and rebuild their commands; never carry model names or
+  flags between runtimes.
+- Mark the job `blocked` when no candidate meets both capability and risk
+  floors. Never budget-route judgment or silently weaken safety.
+
+### 4. Apply the safety gate
+
+- Confirm every job's cwd, allowed files, writable roots, and expected side
+  effects.
+- Use least-privilege permission and tool controls verified on the live runtime.
+- Keep every permission-bypass mode disabled by default.
+- Require explicit user confirmation for `destructive: true`, deployment,
+  release, deletion, credentialed access, or other external side effects unless
+  the user already approved that exact scope through `--yes`.
+- Treat inherently auto-approved headless modes as constrained. Limit them to
+  read/report work or R2-isolated writes; never shared-tree destructive work.
+- Remember that a worktree prevents edit collisions but is not an OS sandbox.
+- Give every CLI process an external timeout. Treat internal timeouts as
+  accounting-only unless the current harness proves cancellation.
+
+### 5. Dispatch and capture
+
+- Create each required worktree before dispatch and pin the job's cwd to it.
+- Start independent jobs together only up to `concurrency`.
+- Update `<run-dir>/state.json` on every job transition.
+- For CLI jobs on a platform where `primekit orchestrate` is supported, delegate the
+  actual process lifecycle (spawn, PID/PGID ownership, TERM-then-grace-then-KILL,
+  survival past this coordinating session) to it instead of tracking a raw
+  subprocess handle in this skill's own process — see
+  [job-spec.md](references/job-spec.md#delegating-cli-job-execution-to-primekit-orchestrate).
+  On a platform where `primekit orchestrate` reports unsupported, fall back to
+  directly spawned, coordinator-owned subprocesses and record that fallback in
+  the report; a coordinator interruption on that fallback path can leave a job
+  running with no supervisor to reconnect to, which is a known, disclosed
+  platform gap rather than a solved case.
+- For CLI jobs, capture redacted command, bounded stdout/stderr, exit status,
+  wall time, artifacts, and usage when reliably reported.
+- For `runtime: internal`, follow
+  [internal-routing.md](references/internal-routing.md): one subagent per job,
+  final text in `result.md`, resolved agent in `status.json`, and no fake
+  subprocess fields.
+- Mark timeout, permission prompt, unknown flag/model, or failed checks as
+  failure. Do not retry silently.
+
+### 6. Run an arbiter review
+
+- Wait for all runnable jobs to settle.
+- Use a separate C3 judgment route selected by
+  [model-routing.md](references/model-routing.md).
+- Prefer independently configured or different-family review when live
+  evidence proves it; disclose a same-family fallback.
+- Compare each result with `expected_output` and the original intent.
+- Run the checks listed in the spec.
+- Flag contradictions, unsupported claims, missing artifacts, safety gaps,
+  timeouts, and failed checks.
+- Do not summarize unverified work as complete.
+
+### 7. Report
+
+- Write `plans/reports/orchestrate-<timestamp>/report.md`.
+- Include per-job status, selected capability/risk tier, resolved runtime and
+  model or agent, artifacts, errors, arbiter verdict, checks, reproduction
+  commands, worktree diffs awaiting integration, and unresolved questions.
+- Append one metrics record per finished job to the cross-run history.
+- Never let metrics or a previous run silently rewrite routing policy.
+
+## Routing Invocation
+
+After live inventory and profiling, invoke
+[model-routing.md](references/model-routing.md) and record its resolved route.
+Do not restate, override, or infer its task defaults, tier floors, candidate
+ranking, internal-agent choice, or fallback rules elsewhere.
+
+## Worktree Isolation
+
+- Create one worktree per isolated job from the accepted base ref.
+- Use a unique branch under the run namespace and set the job's cwd to that
+  worktree.
+- Never share a worktree across jobs or reuse a failed attempt without an
+  explicit cleanup/recovery decision.
+- Sequence jobs that must edit the same generated artifact, lockfile,
+  migration sequence, or shared configuration. Separate worktrees defer those
+  conflicts; they do not resolve them.
+- Integration is coordinator-owned and happens only after the arbiter pass.
+  Summarize diffs first; merging or cherry-picking is a separate reviewed step.
+- Remove only integrated or explicitly discarded worktrees. Preserve failed
+  worktrees for diagnosis and list them in the report.
+
+## Metrics and Self-Improvement
+
+Append one JSON line per finished job to
+`plans/reports/orchestrate-history.jsonl` with:
+
+- run id and job id;
+- runtime and resolved model or agent;
+- task, capability tier, and risk tier;
+- duration, status, exit state, timeout, and attempts;
+- arbiter verdict;
+- usage/cost only when reliably reported by the harness.
+
+Use a meaningful sample of comparable jobs before suggesting policy changes.
+Include evidence-backed suggestions in the report; edit routing references only
+through a separate human-reviewed change.
+
+## Job Spec
+
+Read [job-spec.md](references/job-spec.md) for the full schema. This abbreviated
+example uses placeholders deliberately; preflight resolves them from live
+evidence:
+
+```yaml
+version: 1
+concurrency: 2
+jobs:
+  - id: scout-session-api
+    runtime: internal
+    task: scout
+    cwd: <workspace-root>
+    prompt: "Inspect the session API and report extension points."
+    timeout: 10m
+    expected_output: "Markdown report with files read and recommended seams."
+
+  - id: independent-review
+    runtime: <verified-cli-runtime>
+    fallback_runtime: [<verified-fallback-runtime>]
+    task: review
+    cwd: <workspace-root>
+    prompt: "Review the proposed change and verify its evidence."
+    timeout: 10m
+    expected_output: "Independent verdict with checks and unresolved risks."
+```
+
+Do not replace placeholders from memory. Resolve and record them during that
+run.
+
+## Safety Defaults
+
+- Every job has an explicit cwd, timeout, expected output, and ownership.
+- Capture stays under `plans/reports/orchestrate-<timestamp>/`.
+- Redact secrets and sensitive values from prompts, commands, logs, and reports.
+- Start with read-only or scoped-write behavior.
+- Permission bypasses remain off unless the user approved the exact action and
+  a stronger external isolation boundary contains the residual risk.
+- Parallel writers use separate worktrees and disjoint ownership.
+- Preserve failed output for diagnosis; never hide or relabel it.
+- Keep destructive and credentialed external actions off prompt-only internal
+  isolation.
+
+## Output Layout
+
+```text
+plans/reports/orchestrate-<timestamp>/
+  jobs.yaml
+  runtimes.json
+  state.json
+  report.md
+  worktrees/
+    <job-id>/
+  <job-id>/
+    command.txt         # CLI jobs only
+    stdout.txt          # CLI jobs only
+    stderr.txt          # CLI jobs only
+    result.md           # internal jobs only
+    status.json
+    artifacts/
+    attempt-<n>/
+plans/reports/orchestrate-history.jsonl
+```
+
+`status.json` records the resolved live route rather than a documented default:
+
+```json
+{
+  "id": "independent-review",
+  "runtime": "<resolved-runtime>",
+  "model": "<resolved-model-or-null>",
+  "agent": "<resolved-agent-or-null>",
+  "task": "review",
+  "capabilityTier": "C3",
+  "riskTier": "R0",
+  "status": "success",
+  "exitCode": 0,
+  "durationMs": 0,
+  "timedOut": false,
+  "attempts": 1,
+  "worktree": null
+}
+```
+
+## Arbiter Checklist
+
+The final report is blocked until the arbiter answers:
+
+- Did every required job produce its expected artifact?
+- Did any job fail, time out, request permission, or emit uncertainty?
+- Do outputs contradict each other?
+- Were all listed checks run, and did they pass?
+- Are claims supported by paths, command output, citations, tests, or artifacts?
+- Did every route meet its capability and risk floor?
+- Was runtime/model/agent availability revalidated for this run?
+- Are destructive actions approved and reversible?
+- Are unresolved questions listed plainly?
+
+## Failure Modes
+
+- **Missing or unauthenticated runtime:** evaluate declared fallbacks through
+  the same live policy; otherwise block.
+- **Missing internal agent:** re-resolve against the live agent list; use a CLI
+  fallback only when it meets the same floors.
+- **Unknown flag or model:** fail the attempt, return to live probe, and never
+  guess a replacement.
+- **Permission prompt:** stop the job and report the exact approval boundary.
+- **Timeout:** preserve bounded partial output, fail the job, and block
+  dependents.
+- **Interrupted run:** reload `jobs.yaml` and `state.json`; keep successful
+  outputs, preserve prior attempts, revalidate live routes, and redispatch only
+  interrupted jobs. For any job whose CLI process was delegated to
+  `primekit orchestrate`, reconnect first with
+  `primekit orchestrate resume <run-id> <job-graph.json>` (the same graph file used at
+  dispatch) — this either confirms the still-running worker matches the
+  original launch digest, or reclassifies it as orphaned for this step to act
+  on; it never redispatches a second process tree for a run the supervisor is
+  still tracking.
+- **Ambiguous ownership:** sequence the jobs or assign separate worktrees and
+  an explicit integration step.
+- **Reference disagreement:** stop and report the contract mismatch instead of
+  choosing whichever copied route looks newer.
+
+## Limitations
+
+- Jobs do not share implicit memory; pass required artifacts through explicit
+  dependencies.
+- Internal jobs may not support force cancellation, per-job sandboxing, or
+  model selection.
+- CLI commands, models, authentication, and safety behavior drift; every run
+  revalidates them.
+- Worktrees require a git repository and disk headroom and do not provide
+  process isolation.
+- Metrics are advisory and cannot authorize an automatic route-policy change.
+- Orchestrate coordinates existing runtimes; it does not add a daemon,
+  dashboard, account pool, or provider adapter.
+- `primekit orchestrate` process-lifecycle delegation is Darwin-only in its current
+  version; every other platform reports it unsupported and this skill falls
+  back to coordinator-owned subprocesses with the disclosed interruption gap
+  above, not a silent equivalent guarantee.
+
+## Completion Report
+
+End with:
+
+```markdown
+**Orchestrate Result**
+- Spec: <path or inline request>
+- Report: <plans/reports/orchestrate-.../report.md>
+- Jobs: <success>/<failed>/<blocked>
+- Arbiter: pass|fail|blocked
+- Checks: <commands or none>
+
+Unresolved questions:
+- None
+```

package/skills/orchestrate/references/harness-profiles.md

@@ -0,0 +1,148 @@
+# Harness Profiles
+
+This reference defines the evidence collected for each live orchestration
+harness. It is not a runtime catalog and does not choose routes. The sole
+selection policy is [model-routing.md](model-routing.md).
+
+Harness behavior changes with the installed version, host OS, account policy,
+and invocation mode. Build profiles during preflight and store them in
+`<run-dir>/runtimes.json`; never reuse this document as proof that a runtime is
+installed, authenticated, safe, or capable.
+
+## Profile Schema
+
+Record these fields for every candidate named by the job spec, fallback chain,
+or current internal harness:
+
+| Evidence | What to record |
+| --- | --- |
+| Identity | Runtime id, executable or internal mechanism, live version when exposed |
+| Availability | Resolved path or live agent-list evidence; available, constrained, unavailable, or unverified |
+| Authentication | Non-interactive readiness only; never credentials, tokens, or raw environment values |
+| Headless entry | Verified command shape or internal dispatch mechanism |
+| Working directory | Whether cwd can be pinned and how it is enforced |
+| Model or agent discovery | Live listing mechanism and resolved choices; no copied catalog |
+| Permissions | Approval modes, tool allow/deny controls, and whether headless mode auto-approves |
+| Isolation | OS sandbox, container, worktree, prompt-only boundary, or none |
+| Budgets | Native turn/tool/time controls plus coordinator-owned external timeout |
+| Capture | Structured output, final-result capture, stderr, exit status, artifacts, and usage data |
+| Resume | Supported session or job-state behavior, if verified |
+| Enablement | Instruction files and skill locations actually loaded for this run |
+| Host limits | OS, shell, quoting, path, or sandbox limitations that change the risk posture |
+| Evidence source | Live help/probe and current official documentation consulted for ambiguous behavior |
+
+Use `null` or `unverified` for unknowns. Do not turn absence of evidence into a
+positive capability.
+
+## Confidence States
+
+| State | Meaning | Dispatch consequence |
+| --- | --- | --- |
+| **available** | Required headless path and controls were proven live | Eligible for policy evaluation |
+| **constrained** | Dispatch works, but one or more controls are weaker than requested | Eligible only when the job's risk tier permits those limits |
+| **unverified** | Installed or documented, but the required command, auth, model, or controls were not proven | Advisory work only; never load-bearing |
+| **unavailable** | Missing, unauthenticated, incompatible, or failed probe | Remove from candidate set |
+
+These states are evidence inputs. Capability and risk tier selection remains in
+[model-routing.md](model-routing.md).
+
+## Evidence Collection
+
+For a CLI candidate:
+
+1. Resolve the executable without installing or updating it.
+2. Capture its live version and help output.
+3. Verify only the flags the planned job needs: headless mode, cwd, output,
+   model selection, permissions, and native budgets where applicable.
+4. Use a live model-listing command only when the installed CLI advertises it.
+5. Confirm authentication with a non-secret, non-mutating probe when possible.
+6. Consult current official documentation for behavior that live help cannot
+   establish, and record the page or command checked in the run inventory.
+7. Run no write probe against the user's shared tree.
+
+For `runtime: internal`, profile the current session's agent interface and live
+agent definitions instead of a binary. See
+[internal-routing.md](internal-routing.md).
+
+Unknown flags, aliases, or model identifiers are probe failures. Re-verify the
+candidate; never guess a replacement.
+
+## Safety Evidence
+
+Profile safety behavior by observed control, not product reputation.
+
+- **Approval:** distinguish enforceable per-operation approval, scoped
+  pre-approval, unconditional auto-approval, and unknown behavior.
+- **Tool gating:** record whether read, write, shell, network, and external MCP
+  access can be allowed or denied independently.
+- **Write boundary:** record the enforced writable roots. A cwd argument alone
+  is not a sandbox.
+- **Isolation:** state whether the boundary is OS-enforced, containerized,
+  worktree-only, prompt-only, or absent.
+- **Timeout:** coordinator-owned process timeout is required for CLI jobs even
+  when a native budget exists. Internal timeouts are accounting-only unless
+  the current harness proves cancellation.
+- **Bypass controls:** identify the live runtime's bypass options only to keep
+  them disabled. Never add one to a default command.
+
+An auto-approved or all-or-nothing write path is constrained for any shared
+tree. It may handle read/report work; writing requires isolated R2 treatment
+under [model-routing.md](model-routing.md). Destructive or external work still
+requires explicit approval and the R3 gate.
+
+## Capture Quality
+
+Prefer evidence in this order when otherwise-qualified routes remain:
+
+1. structured event stream plus final result, exit status, and artifacts;
+2. bounded stdout/stderr plus explicit exit status;
+3. final text only with harness-reported status;
+4. unstructured output without trustworthy completion state.
+
+Lower capture quality does not automatically disqualify R0 advisory work, but
+it cannot support a load-bearing check whose result cannot be independently
+verified. Record truncation and preserve useful first/last sections.
+
+## Budget and Reliability Evidence
+
+- Treat native turn, tool-call, or wall-time controls as defense in depth.
+- Enforce an external process timeout for every CLI job.
+- Record observed duration, status, usage, and cost only when the harness
+  reports them reliably.
+- Use cross-run metrics as advisory evidence after enough comparable samples;
+  never let metrics silently rewrite routing policy.
+- A beta, experimental, or partially verified path remains non-load-bearing
+  until live evidence proves the controls required by the job.
+
+## Harness Enablement
+
+Before dispatch, verify the instruction and skill surfaces the live runtime
+actually loads:
+
+1. inspect current runtime documentation or live diagnostics for supported
+   rules and skill locations;
+2. confirm the relevant project/global instruction file and requested skill
+   are present;
+3. name the concrete skill path and expected output in the job prompt;
+4. offer any needed PrimeKit install or refresh as a visible setup step;
+5. never install, update, authenticate, or mutate user configuration silently.
+
+Do not maintain a copied table of runtime-specific paths here. The installed
+runtime and PrimeKit's current projection are execution-time evidence.
+
+## Selection Handoff
+
+After profiling, pass the candidates to
+[model-routing.md](model-routing.md) with:
+
+- live model or agent choices;
+- capability evidence;
+- permission, isolation, and timeout controls;
+- capture confidence;
+- OS limitations;
+- authentication and availability state;
+- cost/latency evidence when trustworthy.
+
+That policy filters by risk first, then capability, reliability, evidence
+quality, and budget. This file must not add task-to-runtime defaults or model
+fallbacks.

package/skills/orchestrate/references/internal-routing.md

@@ -0,0 +1,154 @@
+# Internal Runtime
+
+`runtime: internal` dispatches a job through the current harness's in-session
+subagent mechanism instead of spawning a CLI process. This file owns internal
+dispatch, capture, timeout, and resume mechanics. It does not own route
+selection; apply [model-routing.md](model-routing.md) to the live internal
+profile and any CLI fallbacks.
+
+Internal dispatch is useful when the current session exposes a qualified
+specialist and subprocess startup would add little value. It is not a sandbox:
+agents inherit the session's permission posture unless the live harness proves
+stronger enforcement.
+
+## Live Discovery
+
+Record internal availability in `<run-dir>/runtimes.json` during preflight:
+
+1. Query the current harness for the agent types it can dispatch.
+2. Capture each available agent's live name, description, declared tools,
+   permission boundary, and model metadata when exposed.
+3. Use project or user agent-definition files only as supporting evidence when
+   the live list is unavailable; on-disk presence does not prove session
+   availability.
+4. Record unknown fields as unverified. Never assume a familiar agent name is
+   installed or unchanged.
+
+Do not maintain a copied agent roster here. Installed kits and harness versions
+change the available set.
+
+## Resolution Handoff
+
+Apply the **Internal Branch** in
+[model-routing.md](model-routing.md) to the live profile. That section alone
+owns explicit-agent validation, description-based matching, general-purpose
+fallback, model-independence handling, and the decision to use a CLI fallback
+or block.
+
+This file receives the resolved agent and records it, plus any substitution,
+in `status.json`. It must not add task-to-agent defaults or concrete model
+fallbacks.
+
+## Dispatch Contract
+
+Dispatch one subagent per job. The prompt must include:
+
+- task and expected output;
+- exact `cwd`, plus worktree path when isolated;
+- files the agent may read and write;
+- relevant skill path and instruction files;
+- risk limits, including forbidden external or destructive actions;
+- listed checks the agent may run;
+- `DO NOT COMMIT OR PUSH` unless the coordinator explicitly assigned that
+  authority;
+- instruction to return the deliverable as the final message.
+
+Independent same-stage jobs may launch together up to `concurrency`. Parallel
+writing jobs require disjoint ownership and separate worktrees. The prompt pins
+the agent to its worktree, but that remains prompt-level isolation; never treat
+it as an OS sandbox.
+
+Internal jobs must not perform `destructive: true` or credentialed external
+actions unless the live harness supplies controls that satisfy the R3 policy.
+When it does not, route to a qualified externally isolated candidate or block.
+
+## Tool Boundaries
+
+- Agent-definition tool restrictions are enforceable only to the extent the
+  current harness proves them.
+- Job `allowed_tools` and `disallowed_tools` are advisory prompt constraints
+  unless the harness exposes per-job enforcement.
+- Record whether shell, write, network, and external-tool access can be denied
+  independently.
+- Do not infer least privilege from a specialist name or description.
+
+If a job needs a control the current internal harness cannot enforce, the
+internal candidate does not meet that risk tier.
+
+## Capture Mapping
+
+Internal jobs have no subprocess surface. Map the normal capture contract as
+follows:
+
+| CLI capture | Internal equivalent |
+| --- | --- |
+| `stdout.txt` | `result.md`, containing the subagent's final text |
+| `stderr.txt` | none; harness errors go in `status.json.error` |
+| `command.txt` | none; `status.json.agent` records dispatch identity |
+| exit code | `null`; `status` records success, failed, blocked, or interrupted |
+
+Example `status.json`:
+
+```json
+{
+  "id": "scout-session-api",
+  "runtime": "internal",
+  "agent": "<resolved-live-agent>",
+  "model": null,
+  "task": "scout",
+  "status": "success",
+  "exitCode": null,
+  "durationMs": 0,
+  "timedOut": false,
+  "attempts": 1,
+  "worktree": null
+}
+```
+
+When the harness reports usage or model identity reliably, record it as
+observed metadata without changing the agent-owned model.
+
+## Model Ownership
+
+The resolved agent definition owns its model. Consequences:
+
+- do not set `model:` on an internal job;
+- a model-pinned job requires a live CLI route that supports the pin;
+- do not assume two internal agents use different model families unless live
+  metadata proves it;
+- if independent-family review is required but unprovable internally, use a
+  qualified CLI route or disclose the blocked constraint.
+
+## Timeout
+
+Unless the live harness exposes cancellation, internal timeouts are
+accounting-only. When a job exceeds its bound:
+
+- mark the attempt failed and `timedOut` for orchestration state;
+- do not assume the underlying agent was force-killed;
+- ignore late output unless the user explicitly approves recovery;
+- scope future prompts more tightly instead of relying on timeout enforcement.
+
+Never dispatch a second writer into the same ownership boundary while a timed
+out internal agent may still be running.
+
+## Resume
+
+Resume uses `state.json` like other runtimes:
+
+- successful jobs are skipped and their `result.md` is reused;
+- interrupted jobs are re-dispatched as a new attempt;
+- no subagent session continuity is assumed;
+- prior partial evidence remains under `attempt-<n>/`;
+- runtime and agent availability are revalidated before the new attempt.
+
+## Boundaries
+
+- Internal is fire-and-collect: one prompt in, one final result out.
+- Multi-session teamwork and teammate messaging belong to the team workflow,
+  not orchestrate.
+- A single uncomplicated scout usually does not justify orchestration overhead.
+- Internal agents consume the current session's resources and permission
+  posture.
+- Prompt-level worktree isolation prevents expected edit overlap but does not
+  contain arbitrary process or network access.