@1aboveio/skills 1.0.16 → 1.0.18

package/skills/engineering/harness-runtime/agent-catalog.mjs

@@ -36,7 +36,8 @@
 //   PI_AGENT_CATALOG_COMMAND  JSON argv array: '["node","/abs/agent-catalog.mjs"]'
 //                             (preferred when arguments are needed), or a bare
 //                             executable token: 'pi-agent-catalog'.
-//   default                   pi-agent-catalog on PATH.
+//   default                   pi-agent-catalog on PATH, then (Pi only) the
+//                             catalog in Pi's installed npm packages on ENOENT.
 // A bare token cannot carry arguments — that is deliberate, so no quoting rule
 // sneaks shell semantics in. Nothing here runs npm/npx, resolves a sibling
 // checkout, or reads a registry.
@@ -48,8 +49,9 @@
 // install (`~/.agents/skills/{resolve-issues,harness-runtime}`). No path in this
 // file is relative to a source-domain layout.
 import { spawnSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { resolve as resolvePath } from 'node:path'
+import { readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve as resolvePath } from 'node:path'
 
 export const AGENT_CATALOG_PROTOCOL_VERSION = 1
 export const DEFAULT_AGENT_CATALOG_COMMAND = 'pi-agent-catalog'
@@ -210,6 +212,27 @@ export function resolveCatalogCommand(env = process.env) {
   return parseCommandSpec(spec)
 }
 
+function installedPiCatalogCommand(request, env) {
+  if (request.harness !== 'pi' || env?.[AGENT_CATALOG_COMMAND_ENV]?.trim()) return null
+  const configuredRoot = request.userRoot || env?.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent')
+  const root = configuredRoot === '~' ? homedir()
+    : configuredRoot.startsWith('~/') ? join(homedir(), configuredRoot.slice(2)) : configuredRoot
+  for (const entry of [
+    ['pi-better-harness', 'bin', 'pi-agent-catalog.mjs'],
+    ['pi-better-subagents', 'agent-catalog.mjs'],
+  ]) {
+    const script = resolvePath(root, 'npm', 'node_modules', ...entry)
+    try {
+      if (statSync(script).isFile()) {
+        return { executable: process.execPath, args: [script], source: 'pi-installed' }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error
+    }
+  }
+  return null
+}
+
 function normalizeAvailable(value, label = 'available') {
   if (value === undefined) return { ok: true, available: [] }
   if (!Array.isArray(value)) {
@@ -620,7 +643,8 @@ export function buildCatalogRequest({
   if (normalizedAvailable.available.length === 0) {
     return blocked(
       AGENT_CATALOG_BLOCK_CODES.CAPABILITIES_MISSING,
-      'no current-turn models were supplied; the harness must advertise its available models for this turn',
+      'no current-turn models were supplied: the resolver input has no available[] entries; '
+        + 'collect verified host model and effort evidence before retrying; this does not establish that the harness lacks worker support',
     )
   }
   if (foregroundModel !== null && foregroundModel !== undefined && !nonEmptyString(foregroundModel)) {
@@ -863,17 +887,27 @@ export function resolveAgentCatalog({
   }
   const commandResult = resolveCatalogCommand(env)
   if (!commandResult.ok) return commandResult
-  const { command } = commandResult
+  let { command } = commandResult
+  const invoke = () => runner({
+    executable: command.executable,
+    args: command.args,
+    input: `${JSON.stringify(request)}\n`,
+    timeoutMs,
+    env,
+  })
 
   let run
   try {
-    run = runner({
-      executable: command.executable,
-      args: command.args,
-      input: `${JSON.stringify(request)}\n`,
-      timeoutMs,
-      env,
-    })
+    run = invoke()
+    // Only a missing default command permits installed-package lookup. An
+    // explicit choice or a resolver that ran and failed stays authoritative.
+    if (run?.error?.code === 'ENOENT') {
+      const installed = installedPiCatalogCommand(request, env)
+      if (installed) {
+        command = installed
+        run = invoke()
+      }
+    }
   } catch (error) {
     return blocked(
       AGENT_CATALOG_BLOCK_CODES.COMMAND_UNAVAILABLE,

package/skills/engineering/harness-runtime/contracts.md

@@ -14,4 +14,4 @@ When no supported native question tool is advertised, concise free-text input is
 
 Model discovery and catalog persistence remain separate from question planning. Current-turn tool availability is never inferred from model or harness configuration. Source-tree imports outside `skills/engineering` are unsupported until an installation-aware adapter entrypoint exists; consumers must not copy the runtime to work around that boundary.
 
-`agent-catalog.mjs` is the consumer bridge to the harness-owned agent catalog: one versioned JSON request on stdin (`version`, `harness`, `cwd`, `available`, `foregroundModel`, `fallbackToForeground`, `launchCapabilities`, `hostPreferences`, `overrides`, `tiers`, …) and one JSON response on stdout with four worker slots. It resolves the resolver command from `PI_AGENT_CATALOG_COMMAND` (a JSON argv array, or one bare executable token) or defaults to `pi-agent-catalog` on PATH, runs it with no shell, bounds its output and runtime, and validates the response. Those host fields are validated and forwarded unchanged — nothing is inferred or completed here, so an unstated launch control or tier stays unstated. A missing, broken, or declining resolver is a reported block; the bridge never falls back to a skill-owned model ladder and never installs anything. `discover-models.mjs` and `model-catalog.mjs` remain for consumers that still import them and are no longer part of model-slot selection.
+`agent-catalog.mjs` is the consumer bridge to the harness-owned agent catalog: one versioned JSON request on stdin (`version`, `harness`, `cwd`, `available`, `foregroundModel`, `fallbackToForeground`, `launchCapabilities`, `hostPreferences`, `overrides`, `tiers`, …) and one JSON response on stdout with four worker slots. It resolves the resolver command from `PI_AGENT_CATALOG_COMMAND` (a JSON argv array, or one bare executable token) or defaults to `pi-agent-catalog` on PATH. For Pi only, when that default command is missing (`ENOENT`), it checks the installed `pi-better-harness` then standalone `pi-better-subagents` catalog under `<agent-dir>/npm/node_modules` and invokes the first installed entrypoint through the current Node executable. The agent directory is the request's `userRoot`, then `PI_CODING_AGENT_DIR`, then `~/.pi/agent`. Explicit commands and resolvers that execute but fail remain authoritative; there is no project-checkout search or second resolver after a catalog failure. The bridge runs with no shell, bounds its output and runtime, and validates the response. Those host fields are validated and forwarded unchanged — nothing is inferred or completed here, so an unstated launch control or tier stays unstated. A missing, broken, or declining resolver is a reported block; the bridge never falls back to a skill-owned model ladder and never installs anything. `discover-models.mjs` and `model-catalog.mjs` remain for consumers that still import them and are no longer part of model-slot selection.

package/skills/engineering/resolve-issues/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: resolve-issues
-description: "Slash/explicit-only (/resolve-issues). Drive an issue, epic, or feature spec to reviewed, green PRs, one per issue, merged or handed back merge-ready: preflight, task map, exploration and a per-issue slice check, isolated implementers within live host capacity, then per issue its PR, independent better-review, CI, and queue/merge (or merge-ready hand-back) as soon as it is done. Asks once, at the end of preflight (target branch, merge mode, scheduler mode, plan) and resolves the worker roles' models as run metadata instead of asking, then never blocks on the human; small non-blocking problems collect in a dropbox, posted at the end as grouped ready-for-agent issues. /rush-issues is its no-questions shortcut. Do not auto-select. Use for whole-spec delivery, including high-risk work; risk changes model and validation depth, never the workflow. NOT for release work (resolve-release)."
+description: "Slash/explicit-only (/resolve-issues). Drive an issue, epic, or feature spec to reviewed, green PRs, one per issue, merged or handed back merge-ready: preflight assessment with an explorer only for planning unknowns, a per-issue slice check, isolated implementers within live host capacity, then per issue its PR, independent better-review, CI, and queue/merge (or merge-ready hand-back) as soon as it is done. Asks once, at the end of preflight (target branch, merge mode, scheduler mode, plan) and resolves the worker roles' models as run metadata instead of asking, then never blocks on the human; small non-blocking problems collect in a dropbox, posted at the end as grouped ready-for-agent issues. /rush-issues is its no-questions shortcut. Do not auto-select. Use for whole-spec delivery, including high-risk work; risk changes model and validation depth, never the workflow. NOT for release work (resolve-release)."
 disable-model-invocation: true
 metadata:
   workflow-role: coordinator
@@ -8,7 +8,7 @@ dependencies:
   - better-review
   - golden-path
   - harness-runtime
-release-version: 0.48.0
+release-version: 0.49.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve issues
@@ -54,7 +54,7 @@ after 2 fix rounds without a new low of open P0/P1 path rows; no fixed round cap
 
 ```text
 preflight: ready label -> model fills -> plan draft
-  -> exploration -> size check (only scope or an open question holds a unit, with a split)
+  -> preflight assessment (optional explorer) -> size check (only scope or an open question holds a unit, with a split)
   -> one approval (target branch, merge mode, scheduler mode, plan)
   -> schedule runnable units within live host capacity:
        prepare a unit's workspace when its first worker is admitted (never all units up front)
@@ -77,9 +77,9 @@ Read each procedure right before its stage; never substitute your own.
 
 | Stage | Procedure |
 |---|---|
-| Preflight: ready label, models, plan draft, exploration, size check, approval; what any filed text may say | [references/preflight.md](references/preflight.md) ([Filed text](references/preflight.md#filed-text)) |
+| Preflight: ready label, models, plan draft, assessment, size check, approval; what any filed text may say | [references/preflight.md](references/preflight.md) ([Filed text](references/preflight.md#filed-text)) |
 | Task plan shape and live board | [references/task-plan.md](references/task-plan.md) |
-| Exploration (preflight step 4) | [references/exploration.md](references/exploration.md) |
+| Preflight assessment and optional exploration (step 4) | [references/exploration.md](references/exploration.md) |
 | Implementation loop and opening each PR | [references/implementation.md](references/implementation.md) |
 | Read-only warehouse canary | [references/canary.md](references/canary.md) |
 | Owned workspaces: plan, prepare, cleanup, recover, inventory | [references/workspaces.md](references/workspaces.md) |
@@ -105,7 +105,8 @@ Read each procedure right before its stage; never substitute your own.
   check. When a journey or case you run fails, copy its `NATIVE_FAILURE` line (or the failing step, error and
   evidence path) into the unit's plan row; an exit code alone is not a failure record.
   Leave code changes to workers so your attention stays on scheduling, and record each worker as the
-  unit's `workerKind` (`implement`, `fix`, `review`). Exploration continues the run's one explorer. After a context compaction, read this file in
+  unit's `workerKind` (`implement`, `fix`, `review`). You own preflight findings;
+  delegate unresolved planning unknowns under [exploration.md](references/exploration.md#choose-the-owner). After a context compaction, read this file in
   full again before your next step: the summary keeps the run's state, not these rules. Fill
   free slots before starting your own work, stay within [expire.md](references/expire.md)'s limit, and send
   large output to files (read only the lines you need). Expect Pi's **Completions while busy: Steer active run**
@@ -149,12 +150,13 @@ Follow [preflight.md](references/preflight.md):
 efforts are run metadata, never a question.
 2. **Provisional target:** the default branch.
 3. **Plan draft:** one unit per issue, links, delivery mode; show the board.
-4. **Exploration:** have one explorer record each unit's `slice` and,
-   separately, its `proof`, in every run; reuse prior findings for units
+4. **Preflight assessment:** record each unit's `slice` and,
+   separately, its `proof`, yourself for clear work; use an explorer only
+   for concrete planning unknowns. Reuse prior findings for units
    whose evidence did not change
    ([exploration.md](references/exploration.md#reuse-first)).
 5. **Size check:** run `size-check.mjs` (exit 0; read `verdict`). On `hold` or `stop`, hold the listed
-   units (their dependents wait, not started) and draft their splits (yours when none is drafted); on `exploration-unfinished`, continue the explorer.
+   units (their dependents wait, not started) and draft their splits (yours when none is drafted); on `exploration-unfinished`, complete the findings using step 4's owner routing.
 6. **Approval:** ask once for target, merge mode, scheduler mode, and plan;
    record the answers; plan each unit's branch, workspace, base, and lifecycle
    intent, and prepare a workspace only when its first worker is admitted

package/skills/engineering/resolve-issues/references/exploration.md

@@ -1,16 +1,44 @@
 # Exploration
 
-**One explorer per run, after the plan draft, records what sizes, orders, and
-blocks the units: behaviors, missing prerequisites, proof, line estimates,
-dependencies, contracts, and the questions that hold a unit.**
+**Every run gets a coordinator-owned preflight assessment after the plan draft:**
+behaviors, missing prerequisites, proof, line estimates, dependencies, contracts,
+and the questions that hold a unit. A dedicated explorer is optional.
 In a one-unit run, leave `contracts`, `dependsOn`, and `stacksOn` empty.
 
-## Spawn
+## Choose the owner
+
+Read the issues, applicable repository guidance, and the few code or test paths
+needed to check the plan. For clear, bounded work, write the findings yourself.
+The findings are planning state, not product code; keep detailed code discovery
+with implementers.
+
+Delegate when a concrete unknown could change the plan: uncertain cross-unit
+dependencies or contracts, unclear boundaries or likely splitting, or an unfamiliar
+validation setup. Name the unknown and the affected units in the explorer's brief.
+Multiple units or a high-risk label alone do not require an explorer; unresolved
+planning uncertainty does. An unanswered product decision stays an open question,
+not an invitation for the explorer to invent a requirement.
+
+Use the same record and size check for both paths. Resolve each unit's planning
+unknowns or record its open human decision before approval. On later scope or base
+changes, apply this routing again only to affected units.
+
+Resolve the assessment target to an exact commit before reading code: initially
+the provisional target, then the approved target after a branch change. Record
+that SHA as findings `base`; use it explicitly for reuse checks and any explorer
+checkout. The coordinator's current branch is not evidence of the assessment target.
+
+## Optional explorer
+
+Use at most one explorer at a time per run, on the fleet `explore` row, within
+live host capacity. Reuse that explorer for further investigation when available.
+Give it only the affected units and unknowns. While it writes findings, it owns
+that file exclusively; collect its result before the coordinator updates it.
 
 | Field | Value |
 |---|---|
 | Model | The explorer fill ([preflight.md](preflight.md#1-model-slots)) |
-| Workspace | Read-only checkout of the provisional target; write only the findings directory |
+| Workspace | Read-only checkout at the assessment target SHA; write only the findings directory |
 | Task plan | Absolute `task-plan.json` path; its unit ids key the findings |
 | Prior findings | Newest `.resolve-issues/rush/*/exploration/findings.json` for the same spec locator, if any |
 | Deadline | 15 minutes, plus 1 minute per unit beyond 4 |
@@ -18,15 +46,23 @@ In a one-unit run, leave `contracts`, `dependsOn`, and `stacksOn` empty.
 
 ## Reuse first
 
-**When prior findings exist, explore only the units whose evidence changed.**
-Run, before spawning, and give the explorer its output:
+**Reuse requires unchanged requirements as well as unchanged code evidence.**
+First compare each unit's current criteria, dependency contracts, relevant guidance,
+and recorded decisions with the prior assessment. Reassess affected units even if
+the helper below says `reuse`; it checks Git evidence paths, not those inputs.
+When the prior inputs cannot be established, reassess that unit.
+
+Run the code-evidence check against the exact assessment target, not the caller's
+`HEAD`; include the output and any forced reassessments in an explorer brief:
 
 ```bash
 node <skill-base-dir>/scripts/findings-reuse.mjs \
-  --prior <prior findings.json> --units <this run's unit ids, comma-separated>
+  --prior <prior findings.json> --units <this run's unit ids, comma-separated> \
+  --head <assessment-target-SHA>
 ```
 
-- `reuse`: copy the entry unchanged, with the new `base`.
+- `reuse`: copy the entry unchanged only when the non-code inputs above also
+  match, with the new `base`.
 - `recheck`: re-explore the entry; its `changed` files are where to look.
 - `new`: explore from scratch.
 
@@ -34,7 +70,9 @@ Example: a resumed run starts after earlier units merged `src/charge/`; only
 the two units whose evidence names `src/charge/` are re-explored, the other
 four are copied.
 
-## Brief
+## Assessment record
+
+The coordinator and any delegated explorer use these rules:
 
 1. **Scaffold, then save one unit at a time.** Keep an existing
    `findings.json`; otherwise create it with `version: 2`, the `base` SHA,
@@ -106,7 +144,7 @@ four are copied.
        journey; `local` runs that Charge journey script on an owned emulator,
        not the repository's default phone journey.
      - Findings saved before `local` and `skill` existed are unfinished:
-       continue the explorer to add them, even when reusing the rest.
+       add them before the size check, even when reusing the rest.
    - `physical`: evidence only a real device gives; else empty.
 
    - `groups` and `setups` (only when `slice.newProductBehaviorCount` is
@@ -193,10 +231,14 @@ it then.
 
 ## Completion
 
-Confirm the findings exist, the model read-back matches, and no product source
-changed. Never edit the findings yourself. Run the size check; on `exploration-unfinished` or
-tool failures, continue the explorer with the errors. At the deadline, have it
-save what it has and stop; continue it in the same directory for the units
-still empty while size-check problems plus empty units reach new lows, then follow
-[expire.md](expire.md). Never skip exploration;
-reuse is not skipping.
+Confirm the findings exist and no product source changed. For delegated work,
+also confirm the model read-back matches and inspect the result. Run the size
+check; `exploration-unfinished` means complete or repair the findings, not spawn
+a worker automatically. Correct a missing field yourself when the evidence is
+clear; continue the explorer only for unresolved investigation.
+
+At an explorer's deadline, have it save what it has and stop. Inspect its partial
+findings, complete clear entries yourself, and continue investigation only for
+remaining unknowns while size-check problems plus empty units reach new lows;
+then follow [expire.md](expire.md). Finish the fleet `explore` row once the
+assessment and size check are complete, even when no explorer was needed.

package/skills/engineering/resolve-issues/references/implementation.md

@@ -76,7 +76,7 @@ the same work. A passing setup check is not a substitute for the blocked behavio
 No additional report or result schema is required.
 
 Have the implementer treat findings as leads, find its own code, and report
-any `product`, `scope`, `design`, or `approval` question the explorer missed and any
+any `product`, `scope`, `design`, or `approval` question the assessment missed and any
 human-only proof. Report each question in the result's `decisionNeeded`
 ([expire.md](expire.md#decide-before-you-defer)); add each proof as a
 handback step. Never edit `findings.json`.

package/skills/engineering/resolve-issues/references/preflight.md

@@ -11,10 +11,22 @@ until step 6.
 node <skill-base-dir>/scripts/plan-sync.mjs --find-run --runs .resolve-issues/rush --issue <owner/name#123>
 ```
 
-When it prints a directory, resume that run (`next-actions.mjs --run <dir> --resume` with
-[fresh capacity](implementation.md#live-capacity))
-instead of starting another; its plan picks up whatever the tree gained
-since. It exits 0 whether or not it found a run: no run prints nothing on stdout
+When it prints a directory, reuse that run instead of starting another. Before
+calling the scheduler, reload its plan, decisions and standing orders. Refresh the
+source requirements as described under [issue-tree sync](task-plan.md#issue-tree-sync)
+and resolve the recorded target to its current exact SHA. Apply
+[assessment reuse](exploration.md#reuse-first) against those inputs.
+
+If assessment was interrupted, findings are incomplete, or affected requirements or
+target evidence changed, complete step 4 and rerun step 5 for those units before
+scheduling them. Finish any outstanding step 6 approval once; preserve choices
+already approved. A saved size stop remains held until reassessment clears it or
+its `runWhole` recommendation is accepted. Do not treat a scheduler action as proof
+that assessment or approval finished.
+
+Then resume with `next-actions.mjs --run <dir> --resume` and
+[fresh capacity](implementation.md#live-capacity); its plan picks up whatever the
+tree gained since. The run finder exits 0 whether or not it found a run: no run prints nothing on stdout
 (`--json`: `{"found":false}`). Example: `/rush-issues #12` finds the run whose saved tree holds
 #12 and resumes it, never a second run beside it.
 
@@ -28,7 +40,7 @@ The script exits 0 whenever it ran (2 if it could not); read `outcome` in its JS
 
 - **`ready`:** continue. An open issue is work, whatever its sub-issues
   say: each `rollups` entry (open, every sub-issue closed) is a unit; the
-  explorer records what is left, or that nothing is, and then the handback
+  assessment records what is left, or that nothing is, and then the handback
   says "close #N". Example: held #40's filed prerequisite #41 closed;
   #40 is a rollup and stays a unit.
 - **`unlabeled`:** continue as on `ready`, and record the `missing` issues for
@@ -78,9 +90,11 @@ posts them; they join this run's end-of-run review
 
 ## 1. Model slots
 
-Write this turn's host evidence to a temporary JSON file and run the fast path
-([shared-modules.md](shared-modules.md#model-slots)); record its fills by exact id
-and effort. The skill names the roles — implementer, explorer, diagnoser,
+Follow [model slots](shared-modules.md#model-slots): on Pi, inspect the live native
+catalog first after checking task overrides and authoritative host preferences;
+use the portable resolver when native role resolution is unavailable or cannot
+validate either exact request. Record the actual fills by
+exact id and effort. The skill names the roles — implementer, explorer, diagnoser,
 reviewer — and the harness agent catalog chooses the models, so rank nothing and
 copy nothing from a ladder. The fills are run metadata: show each role's model
 and effort on the board and never ask which model should implement. A model the
@@ -92,14 +106,23 @@ add the repository's deterministic domain checks and review depth, never change
 the workflow or re-choose the model.
 
 Pass a pinned implementer (`implementer=<id[@effort]>` in the invocation) as
-`--implementer`. Any `ok: false` result ends the run at preflight with its `code`
-and `reason`, starting nothing: `pinned-implementer-unavailable` means the pinned
-model is unavailable and no other implementer is substituted, and
-`catalog-unavailable` or `capabilities-missing` means this host cannot resolve
-roles yet. Never revive the old picker or reuse an earlier run's pick.
+`--implementer` on the portable path. A declined result stops preflight with its
+`code` and `reason`, starting nothing: `pinned-implementer-unavailable` means the
+pinned model is unavailable and no other implementer is substituted;
+`catalog-unavailable` means the portable resolver could not be invoked.
+`capabilities-missing` means its input lacks model evidence: repair an omitted
+field from current host evidence and retry, or report precisely what could not
+be obtained. It does not establish a missing harness capability. Never revive
+the old picker or reuse an earlier run's pick.
 Example: `/rush-issues 1aboveio/ai#1545 implementer=gpt-6-luna@high` on a host
 whose catalog does not offer `gpt-6-luna` stops at preflight and starts nothing.
 
+**Catalog limitation:** optional exploration skips the worker, not catalog
+resolution. Both paths still require all four fills, including
+the explorer, even for coordinator-only assessment. Report a missing explorer as
+a catalog block; do not extract other fills from a declined response or substitute
+a model. Explorer-independent resolution needs a supported upstream protocol.
+
 ## 2. Provisional target
 
 Fetch remote heads; record the default branch as `targetBranch`.
@@ -118,11 +141,13 @@ Example: epic #12's #20 (signed release and go/no-go) and #21
 (physical acceptance) stay out of the plan; the run ends when its code units
 land instead of waiting on them.
 
-## 4. Explore
+## 4. Assess the plan
 
-Run [exploration.md](exploration.md) on the provisional target, with any
-prior findings for the same spec. On tool failures or a size-check `exploration-unfinished` verdict,
-continue the explorer with the errors. Add the links the findings show.
+Follow [exploration.md](exploration.md#choose-the-owner) on the provisional
+target, reusing prior findings for the same spec. Write findings yourself for
+clear work; delegate concrete planning unknowns to an optional explorer.
+On tool failures or `exploration-unfinished`, complete the affected findings
+using the same owner routing. Add the links the findings show.
 
 ## 5. Size check
 
@@ -154,7 +179,7 @@ by row 1 of [Never block on the human](#never-block-on-the-human).
 | `ok`, `warn` | Continue |
 | `hold` | Hold the `held` units (their dependents wait, not started); start the `runnable` units |
 | `stop` | Run-wide failure or every unit held; draft the held units' splits |
-| `exploration-unfinished` | Continue the explorer with the error |
+| `exploration-unfinished` | Complete the findings using step 4's owner routing |
 | exit 2 | Fix the plan or command |
 
 Only scope and open questions hold a unit; proof only warns. Add each
@@ -285,7 +310,7 @@ Example: `/resolve-issues` answered "run the rest" files nothing;
    prerequisites keeps its unit, now depending on them.
    Example: #30 splits into #50 and #51, so the sync adds both, drops 30,
    and unit 34, `blocked_by` #30, now waits on 50 and 51.
-4. Continue the explorer for the new units only; rerun the size check.
+4. Assess the new units only using step 4's owner routing; rerun the size check.
 5. Split a still-held slice again only while splitting makes progress: its
    largest slice is smaller than the one before.
    Example: a 7,287-line unit split into 3,455 and 2,150 lines; a held
@@ -348,16 +373,16 @@ in one interaction, with the native single-choice tool when there is one:
 
 Record each answer in `decisions`, then:
 
-- New target: fetch it, continue the explorer to recheck the findings, rerun
+- New target: fetch it, reassess affected findings using step 4's owner routing, rerun
   the size check; ask again only if it worsens to `hold` or `stop`.
-- Trim: drop the scope, continue the explorer to remove its questions and
+- Trim: drop the scope, remove its findings, questions and
   handback items, rerun the size check.
 - File the splits: follow [File a split](#file-a-split); ask again only if
   the size check returns `stop`.
 - Move to later: mark the units `blocked` (`blockedReason: human-decision`, `humanItem: 1`, the human's words as `humanNeed`); they stay in
   this run's plan and resume with it (one run per spec). Never start a
   separate follow-up run for the same spec.
-- Answer: record it, continue the explorer to set the question
+- Answer: record it, set the question
   `resolved: true`, rerun the size check.
 - Run the rest: mark held units `blocked` (`blockedReason: size-hold`) with the split path;
   their dependents stay not started (`pending`).

package/skills/engineering/resolve-issues/references/review.md

@@ -11,7 +11,8 @@ restate its rules in the brief beyond the two below.
 - Reviewer model: a different id from the implementer's
   ([preflight.md](preflight.md#1-model-slots)). Launch the reviewer with the
   plan's recorded reviewer fill — its `launch`, `instructions`, `selection` and
-  `catalogDigest` ([task-plan.md](task-plan.md#worker-selection-on-resume)) — as
+  native `catalogRevision` or portable `catalogDigest`
+  ([task-plan.md](task-plan.md#worker-selection-on-resume)) — as
   structured launch arguments, never as brief text and never a model id
   hardcoded here. On Pi that `launch` is what the live role resolver receives,
   `{ role }` unless an explicit task override or this host's own preference

package/skills/engineering/resolve-issues/references/shared-modules.md

@@ -37,9 +37,56 @@ Owner: the harness agent catalog. The workflow names four **roles** — implemen
 explorer, diagnoser (escalation), reviewer — and the harness decides which model
 fills each one and how that role is launched on this host. The shared bridge is
 [`harness-runtime/agent-catalog.mjs`](../../harness-runtime/agent-catalog.mjs);
-this skill owns no ladder, no tier ranking, and no model list. Write this turn's
-host evidence to a temporary JSON file first (any writable path; the run directory
-does not exist yet at step 1):
+this skill owns no ladder, no tier ranking, and no model list.
+
+### Native Pi preflight
+
+When Pi advertises `agents_catalog` and role-based spawning, use the live catalog
+for a run with no task model/effort override or separately declared authoritative
+host preference. Check those inputs before selecting this path: an unpinned task
+can still have `hostPreferences`. The native catalog resolves roles against this
+session's model registry and effort support; a second, caller-built inventory is
+unnecessary.
+
+1. Call `agents_catalog` with `action: "list"`, then `action: "inspect"` for
+   `developer`, `explorer`, and `reviewer`. Inspect all three even when the explorer
+   will not run. The diagnoser uses the same developer role.
+2. Require each inspection's live `launchable: yes` and `availability: available`,
+   with its actual resolved model and effort. `definitionValid` and
+   `catalogLaunchable` alone establish only definition validity, not runtime
+   availability. A missing or blocked live decision stops preflight with that
+   diagnostic; saved defaults do not replace it.
+3. Record the catalog revision and each role's **actual** model and effort as run
+   metadata. A tier fallback can differ from the displayed default. Use the
+   developer result for implementer and diagnoser. Require the reviewer's actual
+   model id to differ from the implementer's, regardless of effort; otherwise
+   stop and report the conflict without choosing a replacement.
+   Save each fill in `selections` as `source: "native-catalog"`, `role`, `id`
+   (actual model), `key` (`id@effort` when effort is present), `effort` (actual
+   effort), `launch: { role }`, `instructions`
+   from the inspection, and the observed `catalogRevision`. Retain the native
+   inspection as `selection` evidence, including requested/actual values and
+   availability. This is native provenance, not a fabricated portable
+   `selection` object or `catalogDigest`.
+4. Record the later launch by role (`{ role: "developer" }`, `{ role: "explorer" }`, or
+   `{ role: "reviewer" }`), adding the task brief and authorized workspace/tool
+   controls. The native catalog applies its live instructions and defaults again
+   at admission. Record actual launch provenance if it differs from preflight.
+
+This completes model preflight; continue to the provisional target without
+running `preflight-models.mjs` or manufacturing `available[]`. Worker capacity is
+a separate scheduling input, not model evidence. An explicit task model or effort
+override or authoritative host model/effort preference still needs validation for
+that exact request: use the portable path below when the native inspection cannot
+validate it and preserve its structured launch fields. Keep the request; an
+unresolved request does not authorize a default launch.
+
+### Portable preflight
+
+For a host without native role resolution, or a task override or authoritative
+host preference requiring portable validation, write observed host capabilities
+to a temporary JSON file (any writable path; the run directory does not exist yet
+at step 1):
 
 ```json
 { "available": [{ "model": "provider/model", "nativeModel": "host-id", "supportedEfforts": ["medium", "high"] }],
@@ -54,7 +101,7 @@ a field you cannot observe is left out, and the bridge never completes one.
 
 | Field | Meaning |
 |---|---|
-| `available[]` | This turn's models. `nativeModel` is required for a harness whose slots are launched by a bare host id (Codex); pass the ids the spawn primitive advertises, unchanged. `supportedEfforts` is the host's verified list per model. |
+| `available[]` | This turn's models. Each entry needs verified `supportedEfforts`; IDs alone from configuration or `discover-models.mjs` do not supply effort support. `nativeModel` is required for a harness whose slots are launched by a bare host id (Codex); pass the advertised mapping unchanged. |
 | `launchCapabilities` | The launch controls this host exposes: `model`, `effort`, `instructions`, each a boolean. All three must be stated; omission is not "probably true". A native id and an effort say what the catalog chose, never that the adapter can set it. |
 | `hostPreferences` | This host's own role preferences, keyed by **role** (`developer`, `explorer`, `reviewer`), each `{ model?, effort? }`. Below a task override and above the role default: it is how a host says "this machine runs the developer role on this model". |
 | `fallbackToForeground` | Set `true` only when this host may use the foreground model as a fallback. Pi always may; another harness must opt in. Absent, no foreground fallback happens for it. |
@@ -115,6 +162,13 @@ pick, never fall back to the skill-owned catalog, and never let the reviewer sha
 the implementer's model id: the catalog enforces independence, and re-picking a
 replacement here would silently break it.
 
+`capabilities-missing` describes incomplete resolver input, not proof that the
+host cannot launch workers. Check the supplied file and this turn's native
+capability source before declaring a harness limitation. Repair an omitted field
+from verified evidence and retry preflight; if that evidence is unavailable,
+report the exact missing input. Never derive effort ranges from a selected role
+default or use free worker slots as a model inventory.
+
 **No fallback is invented.** The catalog substitutes only an available model from
 the same tier's configured `candidates`, and never for an explicit request: an
 unavailable pin or host preference blocks rather than sliding to a neighbour, and