@mjasnikovs/pi-task 0.39.4 → 0.40.0

package/README.md

@@ -68,10 +68,10 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | `/task-plan <prompt>` | Plan one task with the model — it asks, you answer, ask it something back, or proceed — then run it through `/task`. |
 | `/task-list` | Open the task list in an editor dialog. |
 | `/task-resume [id]` | Resume the most recent (or named) unfinished task. |
-| `/task-cancel` | Cancel the running task (soft-terminal — still resumable). |
+| `/task-cancel` | Stop the running task at the next safe checkpoint (still resumable). Mid-phase it kills the running child; during the implementation turn it lets the turn finish and stops before the gates. |
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume [--unattended]` | Resume the active `/task-auto` run at the next unfinished task. `--unattended` is the boot-hook form: in-flight runs only. |
-| `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
+| `/task-auto-cancel` | Stop the `/task-auto` loop at the next safe checkpoint — the end of the current phase, research worker, implementation turn or gate, not the end of the task (still resumable). During planning it abandons the plan, which is not yet written. |
 | `/task-config` | Toggle pi-task settings in an editor dialog: remote control, auto-commit, verify work, enforce guidelines, project tour, parallel research, research cache, search engine, command timeout, stuck reply retry, yolo mode, debug logs, one `watch:` toggle per live tool, and one `ext:` toggle per installed host extension. |
 | `/remote` | Show the QR code & URLs for the web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
@@ -191,12 +191,25 @@ Fetches a URL, cleans HTML to markdown ([Readability](https://github.com/mozilla
 - The extraction child runs with `--no-tools` to mitigate visible-text prompt injection.
 
 ### `pi-worker-docs`
-Resolves an installed npm package, indexes its `.d.ts` files and README into a local SQLite cache, retrieves the most relevant chunks for your `query`, and passes them to an isolated child that extracts the focused answer. Version-pinned to whatever is in your `node_modules`.
+Resolves an installed package, indexes its API surface and README into a local SQLite cache, retrieves the most relevant chunks for your `query`, and passes them to an isolated child that extracts the focused answer. Version-pinned to whatever the project actually resolved.
 
-- The package must be installed in the project's `node_modules`; otherwise a one-time auto-install into a dedicated cache dir is attempted.
-- The first call for a `(package, version)` pair pays a one-time ingestion cost; later calls are FTS-only.
+**The manifest decides which registry, not the model.** `text`, `base`, `aeson`, `tokio` and `clap` are all real npm packages *and* real Rust/Haskell ones, so a name alone cannot say which was meant — and guessing npm returns a confident answer about an unrelated package. That is a wrong answer, not a miss.
+
+| Ecosystem | Detected by | Surface read | Version comes from |
+| --- | --- | --- | --- |
+| `npm` | `package.json`, or a `node_modules/` directory | the `.d.ts` files the package ships, plus README | the installed `package.json` |
+| `cargo` | `Cargo.toml`, at the directory or one level below it | `.rs` source reduced to public item heads, doc comments and attributes | `Cargo.lock` |
+| `hackage` | `*.cabal`, `cabal.project`, `stack.yaml` or `package.yaml` | `.hs` source reduced to the export list, signatures and type declarations | `dist-newstyle/cache/plan.json`, then `cabal.project.freeze`, then `stack.yaml.lock` |
+
+- **No manifest, no lookup.** In a directory with none of the above the tool refuses, spawns nothing and installs nothing, and points you at `pi-worker-search` / `pi-worker-fetch` instead.
+- **Two manifests** (a Tauri app, say) are resolved by whichever registry already has the package on disk. If neither does, the call is refused as ambiguous and you pass `ecosystem: "cargo"` to say which.
+- A package the project does not have is fetched once into a dedicated cache dir: `npm install --ignore-scripts` for npm, the `.crate` tarball for cargo, the Hackage tarball (or cabal's own cached copy) for hackage.
+- A Haskell **module** name is refused by name — `Data.Aeson` is not a package, `aeson` is.
+- The first call for a `(ecosystem, package, version)` triple pays a one-time ingestion cost; later calls are FTS-only.
 - Cache lives at `${XDG_CACHE_HOME:-~/.cache}/pi-worker/docs.sqlite` — delete it to reset.
 
+**Known gaps.** The rest of pi-task is still npm-shaped: the final gate, repo-health and orientation read the working directory first-wins, so a Tauri repo gets cargo docs answers while the gate runs `bun run test`, not `cargo test`. Phantom-import checking, dependency-name extraction for research enrichment, and the `@types/…` redirect chain are npm concepts and are no-ops elsewhere. Adding an ecosystem is one row in `src/workers/docs-ecosystems.ts` plus its parsers — profiles live in code and arrive as pull requests with tests, never as user configuration.
+
 ## Settings — `/task-config`
 
 Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings persist to `~/.config/pi-task/config.json`.
@@ -226,6 +239,8 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | --- | --- | --- |
 | `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required only when the **Brave** search engine is selected in `/task-config`. |
 | `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
+| `CARGO_HOME` | `pi-worker-docs` | Where crate source checkouts are read from (defaults to `~/.cargo`). |
+| `CABAL_DIR` | `pi-worker-docs` | Where cabal's downloaded package tarballs are read from (also checks `~/.cabal/packages` and `${XDG_CACHE_HOME:-~/.cache}/cabal/packages`). |
 | `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
 | `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
 | `PI_REMOTE_PUSH_DEBUG` | remote push | When set (e.g. `1`), logs push delivery and push-service HTTP status. Off by default. |

package/dist/task/auto-orchestrator.d.ts

@@ -162,6 +162,42 @@ export interface CoveredPlan {
 export declare function coverPlan(ctx: ExtensionCommandContext, cwd: string, deps: AutoDeps, oriented: OrientedFeature, clarifications: string, decomposed: DecomposedPlan, specDangling: DanglingRef[]): Promise<CoveredPlan>;
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export declare function planAuto(ctx: ExtensionCommandContext, cwd: string, feature: string, deps: AutoDeps): Promise<string | null>;
+/**
+ * One best-effort, HOST-GROUNDED extraction: ask a child to emit lines, drop
+ * every line the design does not literally contain, log the kept/emitted split,
+ * and append what survives to a run-level artifact.
+ *
+ * The grounding step is the reason this shape exists rather than a plain child
+ * call. A child asked for interface facts will paraphrase and occasionally invent
+ * them, and an invented fact in a run-level registry is read as
+ * authoritative by every downstream refine/compose/verify. So nothing the child
+ * says is trusted: `ground` re-checks each emitted line against the design text
+ * host-side, and only substrings survive.
+ *
+ * Best-effort by contract. These artifacts SHARPEN planning; none of them gates
+ * it, so a fault here is swallowed rather than failing a run that is otherwise
+ * fine — which is why the whole body sits in one `catch {}`.
+ *
+ * The two call sites (contracts, launch scripts) were byte-identical apart from
+ * the four values this row carries, and the contracts copy parsed its child's
+ * output twice — once for the artifact and once for the log count — because the
+ * duplication made the second parse easy to miss.
+ */
+export declare function runGroundedExtraction<T>(row: {
+    cwd: string;
+    runChild: (name: string, tools: string, prompt: string) => Promise<string>;
+    /** Child name — also the key AUTO_PLAN_STEPS renders in the loader. */
+    child: string;
+    /** Singular noun for the log line ("contract", "script"). */
+    noun: string;
+    /** Log prefix naming the step. */
+    label: string;
+    prompt: string;
+    parse: (raw: string) => T[];
+    /** Keep only what the design itself backs. Runs host-side, never the child. */
+    ground: (emitted: T[]) => T[];
+    append: (cwd: string, kept: T[]) => Promise<void>;
+}): Promise<void>;
 export declare function requestAutoCancel(): void;
 export declare function runAutoLoop(ctx: ExtensionCommandContext, cwd: string, id: string, deps: AutoDeps): Promise<void>;
 export declare function registerTaskAuto(pi: ExtensionAPI): void;

package/dist/task/auto-orchestrator.js

@@ -773,7 +773,8 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
         try {
             verdict = parseCoverageVerdict(await deps.runChild('decompose-coverage', '', DECOMPOSE_COVERAGE_PROMPT(featureForModel, clarifications, titles)));
         }
-        catch {
+        catch (err) {
+            rethrowIfCancelled(err);
             verdict = null;
         }
         const verdictMissing = verdict?.kind === 'incomplete' ? verdict.missing : [];
@@ -796,7 +797,8 @@ export async function coverPlan(ctx, cwd, deps, oriented, clarifications, decomp
                     + `${acc.crossCutting.length} cross-cutting, ${acc.unmapped.length} unmapped; `
                     + `${covered.size} requirement(s) title-grounded`);
             }
-            catch {
+            catch (err) {
+                rethrowIfCancelled(err);
                 // mapping fault — Fix A accounting degrades; the grounded owned-set
                 // above still guards against drops.
             }
@@ -1080,7 +1082,7 @@ export async function planAuto(ctx, cwd, feature, deps) {
  * output twice — once for the artifact and once for the log count — because the
  * duplication made the second parse easy to miss.
  */
-async function runGroundedExtraction(row) {
+export async function runGroundedExtraction(row) {
     try {
         const emitted = row.parse(await row.runChild(row.child, '', row.prompt));
         const grounded = row.ground(emitted);
@@ -1088,10 +1090,32 @@ async function runGroundedExtraction(row) {
             + ` from ${emitted.length} emitted`);
         await row.append(row.cwd, grounded);
     }
-    catch {
+    catch (err) {
+        rethrowIfCancelled(err);
         // best-effort artifact — never a planning blocker
     }
 }
+/**
+ * Let a cancel through a best-effort catch.
+ *
+ * Planning's degrade-quietly catches exist so one weak child cannot sink a plan,
+ * and every one of them predates the `plan:` checkpoint. That checkpoint throws
+ * USER_CANCELLED from inside `runPlanningChild`, so without this the throw reads
+ * as "that extraction failed": planning carries on, writes the AUTO file, and
+ * leaves a resumable run whose contracts silently lost the entries the cancelled
+ * child would have grounded. Cancel means abandon the plan, so it is not a
+ * degradable fault.
+ *
+ * The requirement-extraction catch already gets this right through
+ * `isFatalChildCause`, which covers USER_CANCELLED as well as the fatal kills.
+ * This is the narrow half of the same rule for the catches that guard only an
+ * optional artifact, where promoting every fatal kill would be a behaviour change
+ * this fix has no evidence for.
+ */
+function rethrowIfCancelled(err) {
+    if (err instanceof Error && err.message === USER_CANCELLED)
+        throw err;
+}
 /** The two feature-level planning children, shown as steps in the loader. */
 const AUTO_PLAN_STEPS = {
     'auto-clarify': { step: 'clarify', stepNum: 1 },
@@ -1470,7 +1494,12 @@ async function handleTaskAuto(args, ctx) {
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
                 if (msg === USER_CANCELLED) {
-                    announceDone(ctx, '/task-auto cancelled.', 'warning');
+                    // Say what was thrown away. Planning writes nothing until it
+                    // finishes, so there is no half-plan to resume and no
+                    // /task-auto-resume to offer — the user has to start over,
+                    // and a bare "cancelled" would leave them looking for one.
+                    announceDone(ctx, '/task-auto cancelled — the plan was discarded. Nothing was written; '
+                        + 'run /task-auto again to re-plan.', 'warning');
                     return;
                 }
                 announceDone(ctx, `/task-auto planning failed: ${msg}`, 'error');
@@ -1559,8 +1588,16 @@ async function handleTaskAutoCancel(_args, ctx) {
  * promise "after the current task": the request is now honoured at the next safe
  * checkpoint (see cancel-points.ts), which mid-spec-pipeline is the end of the
  * current phase, not the end of the task.
+ *
+ * It names the seam set rather than the one seam the run happens to be between,
+ * because that seam is not knowable from here — the checkpoint trail says where
+ * the run has BEEN. Naming the set is what stops "next safe checkpoint" reading
+ * as "some time before the run ends", which is how a wait that is really one
+ * research worker gets mistaken for a wait of the whole task.
  */
-const CANCEL_ACK = 'Stopping /task-auto at the next safe checkpoint…';
+const CANCEL_ACK = 'Stopping /task-auto at the next safe checkpoint — the next planning child, or the '
+    + 'end of the current phase, research worker, implementation turn or gate. The model '
+    + 'call already in flight finishes first.';
 /**
  * Deliver a /task-auto-cancel typed in the terminal while a run owns the main
  * loop — the run bracket's `onCancel`. The armed listener watches raw stdin, so

package/dist/task/cancel-points.d.ts

@@ -27,18 +27,42 @@
  *   pre-final-gate (run-final-gate) every task is checked off and committed; the
  *                  whole-repo gate has not started. A resume re-enters the same
  *                  branch.
+ *   plan:<child>   (child-status, runPlanningChild — the one funnel BOTH
+ *                  /task-auto's planning and /task-plan go through) DURABLE BY
+ *                  DISCARD, and the one seam here that is not durable by writing.
+ *                  Nothing planning produces reaches disk until planAuto's final
+ *                  writeTaskFile, so there is no partial plan to resume and no
+ *                  half-state to repair — stopping abandons the whole plan. That
+ *                  is the point: the alternative measured at 13+ minutes of
+ *                  running after the user asked to stop.
+ *   research:<w>   (research-worker) after persistSection. The four workers run
+ *                  serially by default and each one's section is read back by
+ *                  readCached, so a resume skips every worker already on disk.
+ *                  Costs nothing and repeats nothing — the only seam here that is
+ *                  free in both directions.
+ *   impl:post-turn (orchestrator) the implementation turn has ENDED and the spec
+ *                  sections are all on disk. The turn's edits are uncommitted, so
+ *                  a resume re-delivers the spec onto the partly-edited tree —
+ *                  identical to the shipped ESC-then-decline-steer ending.
+ *   gate:post-commit  (task-gates) the task is checked off and its snapshot is in
+ *                  HEAD. Only the enforce pass is skipped, and enforce is
+ *                  re-runnable.
+ *   gate:pre-resolution (task-gates) at the top of the verify-resolution loop, before
+ *                  a round spends a lint fix, a research child or a whole
+ *                  implementation re-run. The task file is demoted there: it
+ *                  still reads `completed` from spec handoff, and the work is
+ *                  neither verified nor committed.
  *
- * DELIBERATELY NOT checkpoints — stopping here is not safe:
- *   - mid implementation turn: uncommitted, half-applied edits. The user's ESC
+ * DELIBERATELY NOT a checkpoint — stopping here is not safe:
+ *   - mid implementation turn. The turn is a host-session turn, not a child, so
+ *     stopping it means abandoning a half-applied edit set with no commit behind
+ *     it. `impl:post-turn` waits for the turn to end instead. The user's ESC
  *     (declined steer) path already covers "stop now, I accept a partial tree".
- *   - between the implementation turn and the gates, or inside the gates: the
- *     work is written but unverified and uncommitted; the gates are what make it
- *     durable. Cancel is observed on the far side, at loop-top.
  */
 /** Every place the cancel flag is polled. A closed union so the tests enumerate
  *  the same set the loop does — and they do: cancel-points.test.ts asserts on the
  *  recorded trail rather than on the loop's own bookkeeping. */
-export type CancelCheckpoint = 'loop-top' | 'pre-task' | 'pre-final-gate' | `phase:${string}`;
+export type CancelCheckpoint = 'loop-top' | 'pre-task' | 'pre-final-gate' | 'impl:post-turn' | 'gate:post-commit' | 'gate:pre-resolution' | `phase:${string}` | `plan:${string}` | `research:${string}`;
 export declare function requestCancel(): void;
 export declare function isCancelRequested(): boolean;
 /**
@@ -61,5 +85,9 @@ export declare function resetCheckpointTrail(): void;
  * @returns true when the caller must stop here.
  */
 export declare function cancelCheckpoint(where: CancelCheckpoint): boolean;
+/** Let only the seams this answers true for fire. Tests only. */
+export declare function onlyCheckpoints(predicate: (where: CancelCheckpoint) => boolean): void;
+/** Back to production: every seam fires. */
+export declare function clearCheckpointSuppression(): void;
 /** Checkpoints crossed since the last reset. */
 export declare function checkpointsCrossed(): readonly CancelCheckpoint[];

package/dist/task/cancel-points.js

@@ -27,13 +27,37 @@
  *   pre-final-gate (run-final-gate) every task is checked off and committed; the
  *                  whole-repo gate has not started. A resume re-enters the same
  *                  branch.
+ *   plan:<child>   (child-status, runPlanningChild — the one funnel BOTH
+ *                  /task-auto's planning and /task-plan go through) DURABLE BY
+ *                  DISCARD, and the one seam here that is not durable by writing.
+ *                  Nothing planning produces reaches disk until planAuto's final
+ *                  writeTaskFile, so there is no partial plan to resume and no
+ *                  half-state to repair — stopping abandons the whole plan. That
+ *                  is the point: the alternative measured at 13+ minutes of
+ *                  running after the user asked to stop.
+ *   research:<w>   (research-worker) after persistSection. The four workers run
+ *                  serially by default and each one's section is read back by
+ *                  readCached, so a resume skips every worker already on disk.
+ *                  Costs nothing and repeats nothing — the only seam here that is
+ *                  free in both directions.
+ *   impl:post-turn (orchestrator) the implementation turn has ENDED and the spec
+ *                  sections are all on disk. The turn's edits are uncommitted, so
+ *                  a resume re-delivers the spec onto the partly-edited tree —
+ *                  identical to the shipped ESC-then-decline-steer ending.
+ *   gate:post-commit  (task-gates) the task is checked off and its snapshot is in
+ *                  HEAD. Only the enforce pass is skipped, and enforce is
+ *                  re-runnable.
+ *   gate:pre-resolution (task-gates) at the top of the verify-resolution loop, before
+ *                  a round spends a lint fix, a research child or a whole
+ *                  implementation re-run. The task file is demoted there: it
+ *                  still reads `completed` from spec handoff, and the work is
+ *                  neither verified nor committed.
  *
- * DELIBERATELY NOT checkpoints — stopping here is not safe:
- *   - mid implementation turn: uncommitted, half-applied edits. The user's ESC
+ * DELIBERATELY NOT a checkpoint — stopping here is not safe:
+ *   - mid implementation turn. The turn is a host-session turn, not a child, so
+ *     stopping it means abandoning a half-applied edit set with no commit behind
+ *     it. `impl:post-turn` waits for the turn to end instead. The user's ESC
  *     (declined steer) path already covers "stop now, I accept a partial tree".
- *   - between the implementation turn and the gates, or inside the gates: the
- *     work is written but unverified and uncommitted; the gates are what make it
- *     durable. Cancel is observed on the far side, at loop-top.
  */
 let requested = false;
 /** Checkpoints actually reached since the last reset, in order. Instrumentation
@@ -71,14 +95,42 @@ export function resetCheckpointTrail() {
  */
 export function cancelCheckpoint(where) {
     crossed.push(where);
-    // CANCEL_AB_ARM=baseline collapses the checkpoint set back to loop-top alone,
-    // so the two arms differ in exactly one thing. Nothing in src/ ever sets it;
-    // the only writer in the tree is cancel-points.test.ts, which uses it to pin
-    // that the extra checkpoints — and only they — are what the flag gates.
-    if (process.env.CANCEL_AB_ARM === 'baseline' && where !== 'loop-top')
+    if (isSuppressed(where))
         return false;
     return requested;
 }
+// ─── Suppression (negative controls) ─────────────────────────────────────────
+/**
+ * Which seams may fire. `null` is production: all of them.
+ *
+ * This is what makes the seam matrix falsifiable, and a predicate rather than a
+ * name list because three of the seams are open-ended (`phase:`, `plan:`,
+ * `research:`) and a list could not name them all.
+ *
+ * The matrix asks one seam at a time — `onlyCheckpoints(w => w === 'pre-task')`
+ * for the assertion, `onlyCheckpoints(() => false)` for its control — so the two
+ * runs differ by exactly that seam and nothing else. Without the control, "the
+ * run stopped here" also passes against a loop that stops everywhere, or one that
+ * stopped for an unrelated reason: several seams see the same raised flag, and
+ * whichever comes first is the one that stops the run.
+ */
+let allowed = null;
+function isSuppressed(where) {
+    // CANCEL_AB_ARM=baseline collapses the set back to loop-top alone — the
+    // original two-arm control, kept because it is the coarse "does the extra
+    // checkpoint set do anything at all" question, which no per-seam control asks.
+    if (process.env.CANCEL_AB_ARM === 'baseline' && where !== 'loop-top')
+        return true;
+    return allowed !== null && !allowed(where);
+}
+/** Let only the seams this answers true for fire. Tests only. */
+export function onlyCheckpoints(predicate) {
+    allowed = predicate;
+}
+/** Back to production: every seam fires. */
+export function clearCheckpointSuppression() {
+    allowed = null;
+}
 /** Checkpoints crossed since the last reset. */
 export function checkpointsCrossed() {
     return crossed;

package/dist/task/child-status.js

@@ -19,9 +19,10 @@
  * gate-wide loader over a child that renders none (`frame: null`, reached when
  * `deps.loader === false` in gate-child), so both must see the same object.
  */
-import { runPhaseChild } from './child-runner.js';
+import { runPhaseChild, USER_CANCELLED } from './child-runner.js';
 import { resolveContextUsage } from './context-usage.js';
 import { startAutoLoader } from './widget.js';
+import { cancelCheckpoint } from './cancel-points.js';
 export class ChildStatus {
     _lastLine;
     _contextUsage;
@@ -95,6 +96,17 @@ export class ChildStatus {
  */
 export async function runPlanningChild(opts) {
     const { ctx, status, phaseDeps, name, tools, prompt, loader } = opts;
+    // SAFE CHECKPOINT (planning): the one funnel every planning child goes through
+    // — orient, clarify, decompose, each coverage round, each grounded extraction,
+    // and /task-plan's children too. Safe by DISCARD rather than by writing:
+    // planning puts nothing on disk before planAuto's closing writeTaskFile, so
+    // there is no partial plan to resume and none to repair. Without it the flag
+    // was read only after planning RETURNED — measured at 13+ minutes of planning
+    // still running after the user asked to stop.
+    if (cancelCheckpoint(`plan:${name}`)) {
+        phaseDeps.logDebug?.(`cancel: abandoning the plan before ${name}`);
+        throw new Error(USER_CANCELLED);
+    }
     const startedAt = Date.now();
     return status.track(ctx, () => ({
         ...(loader.command === undefined ? {} : { command: loader.command }),

package/dist/task/context-attribution.js

@@ -154,17 +154,29 @@ export function splitBulletSpans(context) {
 export function splitBullets(context) {
     return splitBulletSpans(context).map(s => s.text);
 }
+/**
+ * A version block is headed by its REGISTRY, so the heading is open-ended
+ * (`crates.io`, `hackage`). Anything else is one: the widened pattern also reads
+ * headings out of a retrieved README or page BODY, and calling those `docs` would
+ * let a package's own text forge the block that sources a semantics claim.
+ */
+function blockKind(heading) {
+    if (heading === 'freshness-check')
+        return 'freshness-skipped';
+    if (heading === 'docs' || heading === 'url' || heading === 'service')
+        return heading;
+    return 'npm';
+}
 /** Parse the `### npm:` / `### docs:` / `### url:` / `### service:` blocks out of an EXTERNAL CONTEXT header. */
 export function parseContextBlocks(externalContext) {
     const out = [];
-    const re = /^###\s+(npm|docs|url|service|freshness-check)\s*:?\s*(.*)$/gim;
+    // A version block is headed by its REGISTRY, so `npm` is one of several
+    // (`crates.io`, `hackage`). Matching only the fixed words made every non-npm
+    // block invisible to the parser.
+    const re = /^###\s+([A-Za-z][\w.-]*)\s*:?\s*(.*)$/gim;
     let m;
     while ((m = re.exec(externalContext)) !== null) {
-        const kind = m[1].toLowerCase();
-        out.push({
-            kind: kind === 'freshness-check' ? 'freshness-skipped' : kind,
-            subject: m[2].trim()
-        });
+        out.push({ kind: blockKind(m[1].toLowerCase()), subject: m[2].trim() });
     }
     return out;
 }

package/dist/task/external-context.d.ts

@@ -36,6 +36,8 @@ type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep' | 'docsRaw'
 export interface ExternalTargetResult {
     /** Emitted as an `### npm:` block ahead of every body. Absent for url targets. */
     npmVersion?: NpmVersionInfo | null;
+    /** Which registry the version block came from; npm when absent. */
+    registryLabel?: string;
     /**
      * The `### docs:`/`### url:` body. `undefined` means "this target contributes no
      * body block" — and the two call paths draw that line differently ON PURPOSE:
@@ -68,6 +70,11 @@ export interface ExternalContextLookups {
  * question, in front of a waiting user, while research is uncapped and trails its
  * sub-step.
  */
+/** A live version answer and the registry it came from, for the block heading. */
+export interface VersionBlock {
+    info: NpmVersionInfo;
+    label: string;
+}
 export interface ExternalContextPolicy {
     /**
      * Max combined docs+url targets fanned out, packages first. Omit for uncapped
@@ -83,7 +90,7 @@ export interface ExternalContextPolicy {
      * version at all, and a "which version?" question falls back to whatever the
      * model remembers — which is how a dependency gets pinned to a stale major.
      */
-    versionLookup?: (pkg: string) => Promise<NpmVersionInfo | null>;
+    versionLookup?: (pkg: string) => Promise<VersionBlock | null>;
     /** Sub-step label recorded via `deps.recordSubStep`. Omit to record nothing. */
     subStepLabel?: string;
     /**

package/dist/task/external-context.js

@@ -22,6 +22,7 @@
  * Run against a mixed source, the emitted headings come out in exactly that order:
  * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
+import { chooseEcosystem, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
 import { formatNpmVersionSection, npmVersionLookup } from '../workers/npm-version.js';
@@ -61,6 +62,14 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
         }).catch(() => null))),
         Promise.all(versionLookup ? extraVersionPkgs.map(pkg => versionLookup(pkg).catch(() => null)) : [])
     ]);
+    // A docs target that came back WITHOUT a version — a refused ecosystem, a dead
+    // registry — was dropped from `extraVersionPkgs` on the assumption docs would
+    // supply it. Ask for it now, or its block is silently lost.
+    const missedVersionPkgs = versionLookup ?
+        enrichTargets.versionPackages.filter(p => docsTargets.has(p)
+            && !targets.some((t, i) => t.name === p && targetResults[i]?.npmVersion))
+        : [];
+    const missedVersionResults = await Promise.all(missedVersionPkgs.map(pkg => versionLookup(pkg).catch(() => null)));
     const sections = [];
     // npm version blocks lead the section so the model anchors on live version
     // data before reading any docs body. The docs-fetched packages carry their
@@ -69,11 +78,11 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
     // named dep.
     for (const r of targetResults) {
         if (r?.npmVersion)
-            sections.push(formatNpmVersionSection(r.npmVersion));
+            sections.push(formatNpmVersionSection(r.npmVersion, r.registryLabel));
     }
-    for (const v of extraVersionResults) {
+    for (const v of [...extraVersionResults, ...missedVersionResults]) {
         if (v)
-            sections.push(formatNpmVersionSection(v));
+            sections.push(formatNpmVersionSection(v.info, v.label));
     }
     for (let i = 0; i < targets.length; i++) {
         const body = targetResults[i]?.body;
@@ -118,6 +127,44 @@ export async function gatherExternalContext(refined, deps) {
     const fetchRawFn = deps.fetchRaw ?? fetchRaw;
     const npmVersionFn = deps.npmVersionLookup ?? npmVersionLookup;
     const docsQuery = refined.split('\n').find(l => l.trim()) ?? refined;
+    // Which registry to ask, decided PER PACKAGE.
+    //
+    // A cargo-only project's dependency names are crate names, and asking npm
+    // about them returns a real but unrelated package's versions — the exact
+    // confusion the docs tool refuses. But deciding once for the whole repo makes
+    // every polyglot project ambiguous, and then NO version block is emitted at
+    // all: worse than the old always-npm, because the prompts tell the model to
+    // quote a block that will never be there. Each name carries its own evidence,
+    // so each name gets its own answer.
+    const io = defaultEcosystemIo(deps.signal ? { signal: deps.signal } : {});
+    const askNpm = async (pkg) => {
+        const info = await npmVersionFn(pkg, { signal: deps.signal });
+        return info ? { info, label: 'npm' } : null;
+    };
+    const versionLookup = async (pkg) => {
+        const choice = chooseEcosystem({
+            cwd: deps.cwd,
+            declaresPackage: p => p.declaredRange(p.parentPackage(pkg), deps.cwd) !== null,
+            resolvesLocally: p => {
+                try {
+                    p.resolve(pkg, deps.cwd, io);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+        });
+        // No manifest at all keeps npm, which is what a bare directory has always
+        // done. A name genuinely ambiguous between two registries gets no block —
+        // a version from the wrong registry is worse than none.
+        if (!choice.ok)
+            return choice.reason === 'none' ? askNpm(pkg) : null;
+        if (choice.profile.id === 'npm')
+            return askNpm(pkg);
+        const info = await choice.profile.latest(pkg, io);
+        return info ? { info, label: choice.profile.registryLabel } : null;
+    };
     return buildExternalContext(refined, deps, {
         docs: async (pkg) => {
             const r = await docsRawFn({
@@ -128,6 +175,7 @@ export async function gatherExternalContext(refined, deps) {
             });
             return {
                 npmVersion: r.npmVersion,
+                ...(r.registryLabel ? { registryLabel: r.registryLabel } : {}),
                 body: r.kind === 'ok' && r.chunks.length > 0 ?
                     r.chunks
                         .map(c => c.content)
@@ -142,7 +190,7 @@ export async function gatherExternalContext(refined, deps) {
         },
         search: deps.searchFn
     }, {
-        versionLookup: pkg => npmVersionFn(pkg, { signal: deps.signal }),
+        versionLookup,
         subStepLabel: 'enrichment',
         earlyReturnOnNoTargets: true
     });

package/dist/task/orchestrator.js

@@ -37,10 +37,10 @@ import { parseVerifyBlock } from './spec-validation.js';
 import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phantom-imports.js';
 import { titleForDisplay } from './parsers.js';
 import { USER_CANCELLED } from './child-runner.js';
-import { cancelCheckpoint } from './cancel-points.js';
+import { cancelCheckpoint, requestCancel } from './cancel-points.js';
 import { holdImplementation, liveModelControl } from './implementation-hold.js';
 import { rearmCancelListener } from './cancel-input.js';
-import { takeHeldInput } from './mid-run-input.js';
+import { takeHeldInput, isRunActive } from './mid-run-input.js';
 import { withRun, announceTerminal } from './run-bracket.js';
 import { RUN_END_POLICY, runSucceeded } from './run-end.js';
 import { formatTimings } from './timings.js';
@@ -334,6 +334,31 @@ export class TaskRunner {
             await setTaskSection(cwd, id, 'phase timings', formatTimings(this._timings));
             await setTaskSection(cwd, id, 'handoff', `handoff_at: ${new Date().toISOString()}`);
             await this._deliverSpec(ctx);
+            // SAFE CHECKPOINT (post implementation turn): every phase section is
+            // on disk and the turn has ENDED. Its edits are uncommitted, so a
+            // resume re-delivers the spec onto the partly-edited tree — the same
+            // ending the ESC-then-decline-steer path already produces. Front
+            // matter reads `phase: done`, and PHASE_INDEX.done is past every row,
+            // so the resumed run restores all five sections and falls straight
+            // through to _deliverSpec.
+            //
+            // This is also what makes /task-cancel work here at all: the turn
+            // runs in the host session, not as a child, so aborting this runner's
+            // signal never reached it. The command raises the cooperative flag
+            // and this is where the flag is read.
+            //
+            // AWAITED ONLY. On the fire-and-forget /task path _deliverSpec returns
+            // as soon as the spec is sent, so the turn is STARTING, not finished,
+            // and firing here would write `cancelled` over a task the agent then
+            // goes on to implement in full — reported and recorded as stopped
+            // while it runs, and left in a resumable state that re-delivers the
+            // same spec on top of the finished work. Nothing is lost by staying
+            // out: that path has no gates and no loop to stop, the run just ends,
+            // and ESC is what interrupts the turn itself.
+            if (this._implAwaited && cancelCheckpoint('impl:post-turn')) {
+                this._deps.logDebug?.('cancel: stopping after the implementation turn');
+                throw new Error(USER_CANCELLED);
+            }
             return { kind: 'completed' };
         }
         catch (err) {
@@ -795,12 +820,29 @@ async function handleTaskResume(args, ctx) {
 }
 // eslint-disable-next-line @typescript-eslint/require-await
 async function handleTaskCancel(_args, ctx) {
-    if (!activeTask) {
+    // `activeTask` covers the spec phases and the implementation turn — it is set
+    // in TaskRunner._run and cleared in that run's `finally`. The GATES run after
+    // that, so for the whole verify/autofix/enforce stretch there is no runner to
+    // abort and the honest answer is not "No task is running."
+    const runner = activeTask;
+    if (!runner && !isRunActive()) {
         notifyBoth(ctx, 'No task is running.', 'info');
         return;
     }
-    activeTask.cancel();
-    notifyBoth(ctx, `Cancelling ${activeTask.taskId}…`, 'warning');
+    // The cooperative flag is what gives the command one meaning wherever it is
+    // typed: stop at the next point the run can be resumed from. Without it a
+    // cancel during the gates, or during the implementation turn, had nothing to
+    // observe it. The run bracket scopes the flag to the run that raised it.
+    requestCancel();
+    if (!runner) {
+        notifyBoth(ctx, 'Stopping at the next safe checkpoint…', 'warning');
+        return;
+    }
+    // Abort as well: during the spec phases this kills the running child outright
+    // instead of waiting out its remaining minutes, and the phase already on disk
+    // is what a resume starts from.
+    runner.cancel();
+    notifyBoth(ctx, `Cancelling ${runner.taskId}…`, 'warning');
 }
 // ─── Entry point ─────────────────────────────────────────────────────────────
 export function registerTask(pi) {

package/dist/task/phases.js

@@ -4,6 +4,7 @@
  */
 import { fileURLToPath } from 'node:url';
 import { docsFocused } from '../workers/docs-core.js';
+import { detectEcosystems } from '../workers/docs-ecosystems.js';
 import { fetchFocused } from '../workers/fetch-core.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
@@ -550,7 +551,7 @@ export async function phaseResearch(deps, refined) {
             // queries the FILES worker just answered.
             prompt: prior => orientation.block
                 + promptHeader
-                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
+                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined, detectEcosystems(deps.cwd))
                 + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
                 // Empty unless PI_TASK_PROJECT_DOCS_BUDGET is set. The tool-side
                 // half lives in pi-worker-docs.ts; a budget enforced without being