@dtlabs/ai-toolkit 0.16.9 → 0.17.0

package/CHANGELOG.md

@@ -1,4 +1,17 @@
 ## 0.1.4 (2026-07-21)
+## [0.17.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.16.9...v0.17.0) (2026-10-08)
+
+
+### Features
+
+* **task-executor:** consume replan's carry-over record on start ([f4bdbc1](https://github.com/dtlab-tech/ai-toolkit/commit/f4bdbc1da55a89e82196377a09ed66f274136185))
+* **task-executor:** consume replan's carry-over record on start ([ee669fc](https://github.com/dtlab-tech/ai-toolkit/commit/ee669fc83a6eaf248358f4c3bf9087804074192e))
+
+
+### Bug Fixes
+
+* **tests:** gate replan carry-over test on Windows only ([bd46109](https://github.com/dtlab-tech/ai-toolkit/commit/bd4610949537106734f6a47f40b2925d9a53c621))
+
 ## [0.16.9](https://github.com/dtlab-tech/ai-toolkit/compare/v0.16.8...v0.16.9) (2026-10-07)
 
 

package/bin/cli.js

@@ -2642,6 +2642,7 @@ function _executorCurrentBranchRef(projectDir) {
 //     mismatch, not an I/O failure): SUCCESSOR_NOT_APPROVED,
 //     SUCCESSOR_PLAN_NOT_FOUND, PLAN_NOT_FOUND, PLAN_PARSE_ERROR,
 //     REPLAN_UNKNOWN_TASK_MAPPING, ATTEMPT_NUMBER_MISMATCH,
+//     REPLAN_SOURCE_NOT_SUPERSEDED, REPLAN_PLAN_DIGEST_MISMATCH,
 //     STATE_READBACK_MISMATCH, STATE_NOT_FOUND, STATE_TASK_NOT_FOUND,
 //     STATE_ATTEMPT_NOT_FOUND, STATE_TASK_EXISTS, TREE_MISMATCH,
 //     PARENT_MISMATCH, COMMIT_REINSPECTION_MISMATCH,
@@ -2699,6 +2700,7 @@ const EXECUTOR_EXIT_CODE_BY_ERROR_CODE = {
   // 4 — evidence / plan / approval mismatch
   SUCCESSOR_NOT_APPROVED: 4, SUCCESSOR_PLAN_NOT_FOUND: 4, PLAN_NOT_FOUND: 4,
   PLAN_PARSE_ERROR: 4, REPLAN_UNKNOWN_TASK_MAPPING: 4, ATTEMPT_NUMBER_MISMATCH: 4,
+  REPLAN_SOURCE_NOT_SUPERSEDED: 4, REPLAN_PLAN_DIGEST_MISMATCH: 4,
   STATE_READBACK_MISMATCH: 4, STATE_NOT_FOUND: 4, STATE_TASK_NOT_FOUND: 4,
   STATE_ATTEMPT_NOT_FOUND: 4, STATE_TASK_EXISTS: 4, TREE_MISMATCH: 4,
   PARENT_MISMATCH: 4, COMMIT_REINSPECTION_MISMATCH: 4, INTEGRATION_PARENT_MISMATCH: 4,
@@ -2838,6 +2840,7 @@ async function handleExecutorCommand(argv) {
         claudePath: getFlag('--claude-path'),
         taskTimeoutMs: taskTimeoutMsRaw === undefined ? undefined : Number(taskTimeoutMsRaw),
         agentBudgetUsd: agentBudgetUsdRaw === undefined ? undefined : Number(agentBudgetUsdRaw),
+        fromReplanRunId: getFlag('--from-replan-run-id'),
       });
       emitSuccess(result);
 

package/docs/task-executor-bootstrap.md

@@ -70,7 +70,69 @@ For the full flag reference, exit-code table, and JSON result schemas of every s
 
 ---
 
-## 2. Windows-only E-02 qualification
+## 2. Resolving the Claude CLI executable path
+
+`--claude-path` has no documented discovery procedure anywhere in this toolkit —
+`implement-feature`'s SKILL.md only says "ask the user if unknown," and this document, until now,
+only showed `<resolved-claude-cli-path>` as an unexplained placeholder. Found twice independently
+(once resolving it for a real run, once from a fresh install on a different machine reporting no
+standalone `claude` executable anywhere on `PATH`): **try automated discovery first, then
+validate, and only ask the user when discovery is inconclusive** — never silently guess, and
+never trust a path (found or user-supplied) without confirming it actually runs.
+
+**Case A — a standalone CLI install.** A bare `claude`/`claude.exe` reachable on `PATH`
+(`where claude` on Windows, `which claude` on macOS/Linux). This is the common case for a
+terminal-only install (e.g. `npm install -g @anthropic-ai/claude-code`).
+
+**Case B — Claude Code running as a VS Code (or VS Code-family) extension, no standalone CLI on
+`PATH`.** The extension caches its own Claude Agent SDK binary under the editor's own per-OS
+user-data directory, at:
+
+```
+<editor-userdata-root>/agent-host/sdk-cache/claude/<sdk-version>/<platform>/node_modules/@anthropic-ai/claude-agent-sdk-<platform>/claude[.exe]
+```
+
+`<editor-userdata-root>` is Electron's standard per-OS application-data directory (not an
+extension-specific `globalStorage` subfolder — `agent-host` sits directly under it, a sibling of
+`User`/`Cache`/`logs`):
+- Windows: `%APPDATA%\Code` — confirmed directly on a real machine:
+  `C:\Users\<user>\AppData\Roaming\Code\agent-host\sdk-cache\claude\0.3.220\win32-x64\node_modules\@anthropic-ai\claude-agent-sdk-win32-x64\claude.exe`
+- macOS: `~/Library/Application Support/Code` (same relative layout, by VS Code's own standard
+  per-OS data-directory convention — not independently verified in this session)
+- Linux: `~/.config/Code` (same caveat)
+- For VS Code Insiders or another fork, substitute `Code` with that variant's own folder name
+  (e.g. `Code - Insiders`)
+
+Discovery commands (search, do not assume a fixed version — the cached SDK version drifts with
+editor/extension updates):
+
+```powershell
+# Windows
+Get-ChildItem -Path "$env:APPDATA\Code\agent-host\sdk-cache\claude" -Recurse -Filter "claude.exe" -ErrorAction SilentlyContinue |
+  Select-Object -ExpandProperty FullName
+```
+
+```bash
+# macOS/Linux
+find "$HOME/Library/Application Support/Code/agent-host/sdk-cache/claude" \
+     "$HOME/.config/Code/agent-host/sdk-cache/claude" \
+     -iname "claude" -type f 2>/dev/null
+```
+
+**Validate before trusting any path, found or user-supplied** — this is exactly the kind of
+unattended, potentially costly action (`executor start` spawns real, budget-consuming agent
+processes) this toolkit's own Gate Protocol treats with caution elsewhere:
+- Confirm it is a real, executable file, then run `<path> --version` to confirm it actually
+  responds as a Claude CLI — a matching filename is not evidence it works.
+- If discovery finds **zero or more than one** candidate (e.g. several cached SDK versions from
+  past extension updates), do not guess which one — present every candidate found to the user and
+  have them confirm or choose, per SKILL.md's own "ask the user if unknown" rule. A single,
+  unambiguous candidate that passes the `--version` check may be used directly; anything less
+  certain goes back to the user before `executor start` ever runs.
+
+---
+
+## 3. Windows-only E-02 qualification
 
 The executor's process-supervision guarantees — tree-kill of in-flight attempts, tag-based
 worker-liveness scanning, and immediate-stop confirmation — are proven for **Windows only**. This
@@ -93,7 +155,7 @@ all rather than degrading silently.
 
 ---
 
-## 3. Persistence caveats
+## 4. Persistence caveats
 
 These are the real, already-confirmed caveats and limitations discovered during this feature's
 own delivery. Each one is cited to its source rather than paraphrased from memory.

package/docs/task-executor-cli.md

@@ -35,7 +35,7 @@ text-mode output in the current implementation.
 ### `start`
 
 ```bash
-ai-toolkit executor start --project <path> --feature <path> [--max-concurrency N] [--claude-path <path>] [--task-timeout-ms <ms>] [--agent-budget-usd <amount>]
+ai-toolkit executor start --project <path> --feature <path> [--max-concurrency N] [--claude-path <path>] [--task-timeout-ms <ms>] [--agent-budget-usd <amount>] [--from-replan-run-id <uuid>]
 ```
 
 | Flag | Required | Default | Notes |
@@ -46,6 +46,7 @@ ai-toolkit executor start --project <path> --feature <path> [--max-concurrency N
 | `--claude-path` | no | — | Absolute path to the qualified Claude CLI executable |
 | `--task-timeout-ms` | no | — | Forwarded as a Number |
 | `--agent-budget-usd` | no | — | Forwarded as a Number; persisted into run config, not itself enforced |
+| `--from-replan-run-id` | no | — | UUID of a prior run `replan` has already superseded; seeds its carry-over-eligible tasks straight to `checkpointed` instead of `pending` (see "Carrying forward a replan" below) |
 
 Backs `lib/task-executor/index.js`'s `execute()`. Validates gates/config, acquires the
 repo-wide execution lease for a brand-new run, builds an immutable plan snapshot from the
@@ -74,6 +75,22 @@ the task's own `--project` directory — the executor's job is letting a develop
 anywhere under that project, so (unlike pm-phase1/2's read-only-text workers) a narrower
 allowlist is not an option here.
 
+**Carrying forward a replan.** `replan` (below) computes which of an original run's completed
+tasks are eligible to carry forward into a corrected successor plan (`carriesCompletion`,
+commit-reachability based) and durably records that decision — but, on its own, never acts on
+it: a plain `start` on the successor plan dispatches every task fresh from `pending`, discarding
+the eligibility `replan` just computed. `--from-replan-run-id <uuid>` is the explicit way to
+actually consume that record: given the UUID of a run `replan` has already superseded, `execute()`
+validates that run really is `superseded`, reads its `replan` intent, and confirms that intent's
+`successorPlanDigest` matches the plan this `start` call just parsed (`REPLAN_PLAN_DIGEST_MISMATCH`
+otherwise, exit 4) — a prior run that was never actually `replan`-ed throws
+`REPLAN_SOURCE_NOT_SUPERSEDED` (exit 4). Only then are the mapped `newTaskId`s whose
+`carriesCompletion` is `true` seeded straight to `checkpointed`, with a synthetic attempt carrying
+the original task's already-reachable `originalSha` (never re-verified, never re-dispatched in the
+successor run — `terminalReason` records the exact old run/task/attempt provenance for later
+`diagnose`/audit). Never inferred/auto-detected: omitting the flag (the default) carries nothing
+forward, exactly like today.
+
 ### `status`
 
 ```bash
@@ -218,7 +235,10 @@ way. Validates the caller-supplied old→new task mapping against both the origi
 tasks and the successor's plan snapshot, computes carry-completion eligibility per pair
 (read-only), refuses if any original-run attempt's worker liveness is not confirmed dead
 (`LIVE_WORKER_BLOCKS_REPLAN`), then records the mapping as a durable intent and marks the
-original run `superseded`. Never deletes or rewrites any task/attempt evidence.
+original run `superseded`. Never deletes or rewrites any task/attempt evidence. The record this
+writes is not write-only forever: `start`'s own `--from-replan-run-id` (above) is the explicit
+consumer — pass this run's own `runId` there on the successor's `start` call to actually carry the
+eligible tasks forward, instead of the eligibility decision going unused.
 
 ---
 

package/lib/task-executor/index.js

@@ -2715,6 +2715,14 @@ function createSlotPool(maxConcurrency) {
  * @param {string[]} [args.reviewSpawnArgs] - Test-only override of the full
  *   CLI args array forwarded to every runReview call (see runReview's own
  *   args.spawnArgs). Omitted in production.
+ * @param {string} [args.fromReplanRunId] - UUID of a prior run that
+ *   replan() has already superseded, whose carry-over-eligible tasks
+ *   (taskMapping entries with carriesCompletion: true) should be seeded
+ *   directly as 'checkpointed' in this new run instead of 'pending' — never
+ *   inferred/auto-detected, always an explicit operator decision. The
+ *   referenced run's own replan record must have been computed against
+ *   EXACTLY this run's plan (successorPlanDigest must match), or this call
+ *   fails closed before minting a new run at all.
  * @returns {Promise<object>} Versioned result object:
  *   { protocolVersion, runId, runStatus, tasks: [{ taskId, status }] }.
  * @throws {Error} DISPATCH_VALIDATION_ERROR for malformed maxConcurrency;
@@ -2723,9 +2731,14 @@ function createSlotPool(maxConcurrency) {
  *   detached with no explicit args.taskRef; PLAN_NOT_FOUND when this
  *   feature's own Work-Breakdown.md/.csv cannot be read; PLAN_PARSE_ERROR
  *   propagated unmodified from plan.createPlanSnapshot; LEASE_HELD when a
- *   repo-wide execution lease is already held; any error propagated
- *   unmodified from dispatchTaskAttempt/runVerifications/runReview/git.js/
- *   store.js for a systemic (non-task-attempt) failure.
+ *   repo-wide execution lease is already held; REPLAN_SOURCE_NOT_SUPERSEDED
+ *   when args.fromReplanRunId's own run is not runStatus 'superseded';
+ *   REPLAN_PLAN_DIGEST_MISMATCH when its replan record was computed against
+ *   a different plan than the one this call just parsed; STATE_NOT_FOUND/
+ *   STATE_CORRUPTED/INTENT_NOT_FOUND/INTENT_CORRUPTED propagated unmodified
+ *   while reading args.fromReplanRunId's state/replan record; any error
+ *   propagated unmodified from dispatchTaskAttempt/runVerifications/
+ *   runReview/git.js/store.js for a systemic (non-task-attempt) failure.
  */
 async function execute(args) {
   // Platform qualification guard (US-08-TASK-BE-05) — the single most
@@ -2803,6 +2816,70 @@ async function execute(args) {
   const commonDir = _resolveCommonGitDir(projectDir);
   const executionRoot = path.join(commonDir, 'ai-toolkit', 'execution');
 
+  // Carry-over from a prior replan() decision (US-06-TASK-BE-03's own
+  // "does not auto-start successor" scope boundary — this is the previously
+  // missing other half: an explicit, never-implicit way for a successor
+  // execute() to actually consume what replan() already computed and
+  // durably recorded, instead of that record being write-only forever).
+  // Validated BEFORE minting a new runId/acquiring the lease — a bad
+  // --from-replan-run-id must fail closed before any new run exists at all,
+  // never after. `args.fromReplanRunId` is never inferred/auto-detected
+  // (e.g. by scanning for a 'superseded' run whose replan record's
+  // successorPlanDigest matches this plan) — same "never guess, always
+  // explicit" discipline replan()'s own --task-mapping-json already
+  // established; the operator names the exact source run.
+  let carryOverByNewTaskId = null;
+  if (args.fromReplanRunId !== undefined) {
+    _requireNonEmptyString(args.fromReplanRunId, 'execute: args.fromReplanRunId');
+    const originalRunId = args.fromReplanRunId;
+
+    // Propagates STATE_NOT_FOUND/STATE_CORRUPTED unmodified — a bad run-id
+    // is never silently treated as "nothing carries forward".
+    const originalState = store.readState(executionRoot, originalRunId);
+    if (originalState.runStatus !== 'superseded') {
+      throw _err(
+        'REPLAN_SOURCE_NOT_SUPERSEDED',
+        'execute: --from-replan-run-id "' + originalRunId + '" has runStatus "' + originalState.runStatus +
+          '", not "superseded" — only a run replan() has already superseded may be used as a carry-over ' +
+          'source (never a still-running, paused, or already-completed run)'
+      );
+    }
+
+    // Propagates INTENT_NOT_FOUND/INTENT_CORRUPTED unmodified — replan()
+    // always writes this record BEFORE superseding (see its own step 7/8
+    // ordering), so a superseded run with no readable record here is treated
+    // as corrupted evidence, never as "nothing carries forward".
+    const replanRecord = store.readIntent(executionRoot, originalRunId, 'replan');
+
+    if (replanRecord.successorPlanDigest !== snapshot.planDigest) {
+      throw _err(
+        'REPLAN_PLAN_DIGEST_MISMATCH',
+        'execute: the Work Breakdown just parsed for this run (planDigest "' + snapshot.planDigest +
+          '") does not match the successor plan replan() recorded for run "' + originalRunId +
+          '" (planDigest "' + replanRecord.successorPlanDigest + '") — refusing to carry forward ' +
+          'completions computed against a plan this run is not actually starting'
+      );
+    }
+
+    // Only entries the human/caller already approved as carrying forward
+    // (replanRecord.taskMapping's own carriesCompletion, computed by
+    // replan() from real commit-reachability — see its own doc comment) are
+    // ever applied; every other mapped or unmapped task starts 'pending' and
+    // is dispatched normally.
+    carryOverByNewTaskId = new Map();
+    replanRecord.taskMapping.forEach(function (m) {
+      if (m.carriesCompletion !== true) return;
+      const oldTask = originalState.tasks[m.oldTaskId];
+      const oldAttempt = oldTask.attempts[oldTask.attempts.length - 1];
+      carryOverByNewTaskId.set(m.newTaskId, {
+        oldTaskId: m.oldTaskId,
+        oldAttemptNumber: oldAttempt.number,
+        originalSha: oldAttempt.originalSha,
+        integratedSha: oldAttempt.integratedSha,
+      });
+    });
+  }
+
   const runId = crypto.randomUUID();
   // Fail closed if already held — this is a brand-new run; reclaiming a
   // stale lease is an explicit reconcile/resume/replan decision, never an
@@ -2836,6 +2913,34 @@ async function execute(args) {
     snapshot.tasks.forEach(function (task) {
       state = state.addTask(task.id, { dependencies: task.dependsOn });
     });
+
+    // Seed carry-over tasks straight to 'checkpointed' with a synthetic
+    // attempt recording the ORIGINAL run's already-reachable commit SHA —
+    // never dispatched, never re-verified in this run, exactly mirroring
+    // what a real successful N=1 completion already looks like
+    // (finalizeTaskCheckpoint also only ever registers originalSha, never
+    // integratedSha, for the N=1 case this executor supports today — copied
+    // here verbatim, usually null, never fabricated). 'checkpointed' (not
+    // 'skipped' — that status means "verified+reviewed in THIS run and
+    // found to need no change", a different, honest outcome) is already
+    // terminal-success everywhere that matters: the nonTerminalIds filter,
+    // allTerminalSuccess, and the readyTaskId dependency-satisfaction check
+    // all already treat it as such, unchanged. terminalReason documents the
+    // provenance for any later diagnose/audit — this task has zero real
+    // attempts in the CURRENT run otherwise.
+    if (carryOverByNewTaskId) {
+      carryOverByNewTaskId.forEach(function (carry, newTaskId) {
+        if (!state.tasks[newTaskId]) return; // replan() already validated newTaskId exists; defensive only
+        state = state.addAttempt(newTaskId, { stage: 'committed' });
+        state = state.updateAttempt(newTaskId, 1, {
+          originalSha: carry.originalSha,
+          integratedSha: carry.integratedSha,
+          terminalReason: 'carried-over-from-replan:' + args.fromReplanRunId + ':' + carry.oldTaskId + '#' + carry.oldAttemptNumber,
+        });
+        state = state.setTaskStatus(newTaskId, 'checkpointed');
+      });
+    }
+
     store.writeState(executionRoot, runId, state);
 
     const tasksById = new Map(snapshot.tasks.map(function (t) { return [t.id, t]; }));
@@ -3792,7 +3897,10 @@ function _hasGate2Approval(approvalsText) {
  *
  * Does NOT dispatch, start, or touch the successor run in any way (per its
  * own scope — see the module-level file comment's original stub doc, which
- * this replaces).
+ * this replaces). The record this writes is NOT write-only forever, though:
+ * execute()'s own args.fromReplanRunId explicitly consumes it, seeding any
+ * carriesCompletion:true mapping straight to 'checkpointed' in the
+ * successor run — see execute()'s own doc comment.
  *
  * @param {object} args
  * @param {string} args.executionRoot - Absolute path to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.16.9",
+  "version": "0.17.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/skills/implement-feature/SKILL.md

@@ -248,7 +248,11 @@ ai-toolkit executor start \
 
 Placeholders:
 - `<path-to-feature.md>` — the feature.md path passed to this skill
-- `<resolved-claude-cli-path>` — the Claude CLI executable path on this host; ask the user if unknown
+- `<resolved-claude-cli-path>` — the Claude CLI executable path on this host; try automated
+  discovery first (`docs/task-executor-bootstrap.md` section 2 — covers both a standalone CLI on
+  `PATH` and the VS Code-extension-cached SDK binary case), validate any candidate with
+  `--version` before trusting it, and ask the user only when discovery is inconclusive or finds
+  more than one candidate
 - `<task-timeout-ms>` and `<agent-budget-usd>` — must be supplied explicitly; there is no hidden default timeout or spend
 
 **If the host's ordinary terminal capability can launch a durable external command**, launch