agentplane 0.3.1 → 0.3.3

package/assets/AGENTS.md

@@ -17,7 +17,7 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 - Repository type: user project initialized with `agentplane`.
 - Gateway role: keep this file compact and deterministic; move scenario-specific details to policy modules.
 - CLI rule: use `agentplane` from `PATH`; if unavailable, stop and request installation guidance (do not invent repo-local entrypoints).
-- Startup shortcut: run `## COMMANDS -> Preflight`, then apply `## LOAD RULES` before any mutation.
+- Startup shortcut: run `## COMMANDS -> Preflight`, then read `docs/user/agent-bootstrap.generated.mdx`, then apply `## LOAD RULES` before any mutation.
 
 ---
 
@@ -28,7 +28,7 @@ Priority order (highest first):
 1. Enforcement: CI, tests, linters, hooks, CLI validations.
 2. Policy gateway: `AGENTS.md`.
 3. Canonical policy modules from `## CANONICAL DOCS`.
-4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/config.json`.
+4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `docs/user/agent-bootstrap.generated.mdx`, `.agentplane/config.json`.
 5. Reference examples from `## REFERENCE EXAMPLES`.
 
 Conflict rule:
@@ -66,7 +66,7 @@ agentplane task plan set <task-id> --text "..." --updated-by <ROLE>
 agentplane task plan approve <task-id> --by ORCHESTRATOR
 agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
 agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
-agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
+agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
 ### Verification
@@ -83,6 +83,7 @@ node .agentplane/policy/check-routing.mjs
 ## TOOLING
 
 - Use `## COMMANDS` as the canonical command source.
+- Use `docs/user/agent-bootstrap.generated.mdx` as the canonical startup path for agent onboarding.
 - For policy changes, routing validation MUST pass via `node .agentplane/policy/check-routing.mjs`.
 
 ---
@@ -194,5 +195,5 @@ Detailed DoD rules are in `.agentplane/policy/dod.core.md`, `.agentplane/policy/
 ## CHANGE CONTROL
 
 - Follow incident-log, immutability, and policy-budget rules in `.agentplane/policy/governance.md`.
-- Record situational incident rules only in `.agentplane/policy/incidents.md`.
+- Record situational incident rules only in `.agentplane/policy/incidents.md`; do not load/read that file during normal startup unless the task directly touches it or recovery/incident handling requires it.
 - Keep `AGENTS.md` as a gateway; move detailed procedures to canonical modules.

package/assets/agents/CODER.json

@@ -9,7 +9,7 @@
   "outputs": [
     "Code and config updates describing exact hunks, commands run, and rationale.",
     "Transition guidance for the referenced task (status suggestions, blockers, follow-ups).",
-    "Verification notes highlighting command outputs, test coverage, and remaining questions."
+    "Task README updates aligned with the active doc contract, including acceptance-oriented Verify Steps and task-local Findings when needed."
   ],
   "permissions": [
     "Project files: read + write within the active task scope.",
@@ -21,8 +21,9 @@
     "Confirm task context and readiness before editing; keep diffs minimal and task-scoped.",
     "Document edits with before/after snippets and cite the exact files touched.",
     "Run necessary commands (tests/linters/formatters) and summarize key output lines only.",
-    "Prefer declared verify commands; record ad-hoc results via PR notes or request PLANNER to update verify lists.",
-    "Coordinate handoffs to TESTER/REVIEWER/DOCS only when those roles already have explicit executable tasks; otherwise keep notes and verification in the same task.",
+    "Prefer declared verify commands; treat `Verify Steps` as the acceptance contract and request PLANNER updates when the contract itself drifts.",
+    "Record local deviations, follow-ups, and incident candidates in the task-local observation section (`Notes` for v2, `Findings` for v3); do not promote directly into policy incidents.",
+    "Coordinate handoffs to TESTER/REVIEWER/DOCS only when those roles already have explicit executable tasks; otherwise keep findings and verification in the same task.",
     "Avoid task closure in branch_pr; keep commits task-scoped and update status via agentplane."
   ]
 }

package/assets/agents/DOCS.json

@@ -17,7 +17,7 @@
   ],
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Create/update task README content via agentplane task doc set; required sections are config-driven (check config if they differ).",
+    "Create/update task README content via agentplane task doc set; keep the active doc_version contract explicit and treat v3 `Findings` as task-local observation memory, not policy incidents.",
     "Update user/developer docs minimally to reflect behavior and match existing tone.",
     "Keep PR artifact docs and notes current when required; add handoff notes for INTEGRATOR.",
     "Avoid extra commits and standalone docs-only tasks unless documentation itself is the independent deliverable."

package/assets/agents/INTEGRATOR.json

@@ -20,7 +20,7 @@
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Operate from the repo root on the pinned base branch; run pr check -> integrate -> finish via agentplane.",
     "Use configured base branch and task branch prefix when referencing branches; check config if uncertain.",
-    "Ensure verify commands are run/recorded; update PR artifacts and task README as needed.",
+    "Ensure verify commands are run/recorded against the declared Verify Steps contract; update PR artifacts and task README findings as needed.",
     "When closing multiple tasks, use batch finish so the same commit metadata and verification note apply.",
     "Check `closure_commit_requires_approval` in .agentplane/config.json; ask for user approval before the final closure commit when true, otherwise proceed without confirmation. Optionally clean task branches/worktrees after closure."
   ]

package/assets/agents/ORCHESTRATOR.json

@@ -19,6 +19,7 @@
     "Convert the first user message into an execution plan; do not create tasks until the user approves it.",
     "Restate the user goal and constraints, then draft a numbered execution plan with agent assignments and expected outcomes.",
     "Build a task graph from the approved plan: split into atomic tasks, each with one specific owner from existing agent IDs; schedule CREATOR if a required agent is missing.",
+    "When task artifacts are part of scope, keep the active README contract explicit: Verify Steps define acceptance, and task-local observations stay in Notes/Findings rather than policy incidents.",
     "For development work, select the minimal role set needed for risk and workflow mode; do not split work by role labels alone.",
     "Use TESTER/REVIEWER/INTEGRATOR as independent tasks only when risk, mode (`branch_pr`), or a hard verification/integration boundary requires it; otherwise keep work in one executable task.",
     "If the user explicitly requests agent optimization, invoke UPDATER and pause until its analysis is complete.",

package/assets/agents/PLANNER.json

@@ -21,6 +21,7 @@
     "If task graph planning yields exactly one work item, create exactly one task and keep full traceability there.",
     "Split goals into atomic tasks with one specific owner each; set depends_on explicitly (use [] for none).",
     "Create tasks with valid parameters: non-empty title/description/owner, at least one meaningful tag, deduped depends_on/verify.",
+    "Write Plans as executable steps and treat Verify Steps as concrete acceptance checks; keep task-local observations in Notes/Findings rather than policy incidents.",
     "Before creating a new task, check open tasks (`TODO|DOING|BLOCKED`) and reuse/update a matching task when scope and owner align.",
     "Do not create separate tasks for role handoffs unless there is an independent deliverable, a different required owner, or an explicit dependency boundary.",
     "Do not create standalone tasks for scaffolding/doc bookkeeping/status transitions; keep those updates inside the executable task unless there is a real deliverable boundary.",

package/assets/agents/TESTER.json

@@ -10,7 +10,7 @@
   "outputs": [
     "New or updated tests covering relevant behavior and edge cases.",
     "A short list of executed local commands with key pass/fail lines only.",
-    "Notes on remaining coverage gaps or required follow-ups."
+    "Verification outcomes mapped to Verify Steps plus task-local findings on remaining gaps or follow-ups."
   ],
   "permissions": [
     "Project files: read + write for tests and minimal supporting code.",
@@ -22,6 +22,8 @@
     "Add the smallest set of high-value tests (happy path + edge/regression).",
     "Keep tests deterministic and fast; avoid network calls and time-based flakiness.",
     "Run targeted tests first and summarize only the key output lines.",
+    "Check results against `Verify Steps` as the acceptance contract, not just against ad-hoc commands.",
+    "Record residual gaps in the task-local observation section (`Notes` for v2, `Findings` for v3) rather than escalating them directly into policy incidents.",
     "If test infrastructure is missing, document the blocker in the same task first; request a PLANNER task only if it is a separate, independent deliverable."
   ]
 }

package/assets/policy/dod.code.md

@@ -8,9 +8,9 @@ Apply when task changes implementation/source code.
 - Run all checks listed in task `## Verify Steps` (or record approved skips)
 - `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`
 
-## Verification notes contract
+## Verification evidence contract
 
-Record verification in task notes using this compact template:
+Record verification via `agentplane verify ...` and keep residual gaps or follow-ups in the task-local observation section (`Notes` in `doc_version=2`, `Findings` in `doc_version=3`) using this compact template:
 
 - `Command`: exact command string.
 - `Result`: `pass` or `fail`.

package/assets/policy/dod.core.md

@@ -10,9 +10,11 @@ The task is complete only if all core checks are true:
 6. Drift was either absent or explicitly re-approved.
 7. Final repo state contains no unintended tracked changes.
 
-## Required task notes template
+## Required task README contract
 
-Every non-trivial task README must contain non-empty sections:
+Every non-trivial task README must satisfy the active `doc_version` contract.
+
+Legacy `doc_version=2` tasks use:
 
 - `Summary`
 - `Scope`
@@ -22,6 +24,18 @@ Every non-trivial task README must contain non-empty sections:
 - `Rollback Plan`
 - `Notes`
 
+Target `doc_version=3` tasks use:
+
+- `Summary`
+- `Scope`
+- `Plan`
+- `Verify Steps`
+- `Verification`
+- `Rollback Plan`
+- `Findings`
+
+`Findings` is task-local. Policy incidents are curated separately in `.agentplane/policy/incidents.md`.
+
 ## Material drift criteria
 
 Treat drift as material and require re-approval when at least one is true:

package/assets/policy/dod.docs.md

@@ -8,9 +8,9 @@ Apply when task changes docs or policy files only.
 - `agentplane doctor`
 - Targeted lint/tests if docs generation or scripts were changed.
 
-## Verification notes contract
+## Verification evidence contract
 
-Record docs/policy verification in task notes using this template:
+Record docs/policy verification via `agentplane verify ...` and keep residual deviations or follow-ups in the task-local observation section (`Notes` in `doc_version=2`, `Findings` in `doc_version=3`) using this template:
 
 - `Command`: exact command string.
 - `Result`: `pass` or `fail`.

package/assets/policy/incidents.md

@@ -33,4 +33,47 @@ example:end -->
 
 ## Entries
 
-- None yet.
+- id: INC-20260308-01
+  date: 2026-03-08
+  scope: release apply internal push path
+  failure: release apply re-entered local pre-push hooks and could stall after creating the local release commit and tag
+  rule: Release orchestration MUST push its own release refs without recursively re-entering local pre-push hooks.
+  evidence: task 202603061532-9Y41NM; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 4
+  enforcement: test + command implementation
+  state: stabilized
+
+- id: INC-20260308-02
+  date: 2026-03-08
+  scope: stale-dist guard in framework checkout
+  failure: stale-dist enforcement treated git dirtiness as stale runtime and blocked diagnostics or rebuilt checkouts incorrectly
+  rule: Stale-dist freshness MUST compare current runtime inputs against the recorded build snapshot, and read-only diagnostics MUST warn-and-run instead of hard-failing on dirty runtime trees.
+  evidence: tasks 202603072032-2M0V8V, 202603072032-1BC7VQ, 202603072032-V9VGT2, 202603072032-4D9ASG
+  enforcement: test + runtime guard
+  state: stabilized
+
+- id: INC-20260308-03
+  date: 2026-03-08
+  scope: framework checkout PATH resolution
+  failure: contributors inside the framework repo could execute an older global agentplane binary instead of the checkout they were editing
+  rule: Inside the framework checkout, agentplane resolved from PATH MUST hand off to the repo-local runtime by default unless an explicit global opt-out is set.
+  evidence: tasks 202603071647-M0Q79C, 202603071647-Y4BZ1T, 202603071647-25WS52
+  enforcement: test + wrapper logic
+  state: stabilized
+
+- id: INC-20260308-04
+  date: 2026-03-08
+  scope: release mutation generated surfaces
+  failure: release apply could leave version-sensitive generated docs stale until later parity checks failed
+  rule: Release mutation MUST regenerate and stage generated docs that encode released package versions as part of the release commit itself.
+  evidence: task 202603071745-T3QE04; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 5
+  enforcement: test + release mutation
+  state: stabilized
+
+- id: INC-20260308-05
+  date: 2026-03-08
+  scope: release mutation repository CLI expectation
+  failure: repository-owned framework.cli.expected_version could drift behind the actual released version because release apply did not persist it
+  rule: Release mutation MUST keep framework.cli.expected_version aligned with the released package version whenever repository config is present.
+  evidence: tasks 202603081315-Y4D6AE, 202603081538-GF7P9C; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 3
+  enforcement: test + release mutation
+  state: stabilized

package/assets/policy/workflow.direct.md

@@ -7,8 +7,10 @@ Use this module when `workflow_mode=direct`.
 1. CHECKPOINT A: run preflight and publish summary.
 2. CHECKPOINT B: build task graph and obtain explicit user approval.
 3. Create/reuse task ID.
-4. Fill task docs (`Summary/Scope/Plan/Risks/Verify Steps/Rollback/Notes`).
-   Batched doc updates are allowed: sections may be updated in one turn/message via one full-doc payload or multiple `task doc set` operations, as long as approval has not started yet.
+4. Fill task docs for the active README contract.
+   - `doc_version=2`: `Summary/Scope/Plan/Risks/Verify Steps/Rollback/Notes`
+   - `doc_version=3`: `Summary/Scope/Plan/Verify Steps/Verification/Rollback/Findings`
+     Batched doc updates are allowed: sections may be updated in one turn/message via one full-doc payload or multiple `task doc set` operations, as long as approval has not started yet.
 5. Approve plan (if required), then start task sequentially.
 6. Implement changes in current checkout.
 7. Run verification commands from loaded DoD modules.
@@ -23,7 +25,7 @@ agentplane task plan set <task-id> --text "..." --updated-by <ROLE>
 agentplane task plan approve <task-id> --by ORCHESTRATOR
 agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
 agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
-agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
+agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
 ## ERROR RECOVERY
@@ -31,16 +33,19 @@ agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "...
 If any step fails:
 
 1. Stop mutation immediately.
-2. Record failure details in task `Notes` (`what failed`, `where`, `impact`).
+2. Record failure details in the task-local observation section.
+   - `doc_version=2`: task `Notes`
+   - `doc_version=3`: task `Findings`
 3. Mark task blocked: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`.
 4. Request re-approval before scope/risk changes.
-5. If failure is process/policy-related, append entry to `.agentplane/policy/incidents.md`.
+5. If failure is process/policy-related and strong enough for repo-wide memory, promote it explicitly into `.agentplane/policy/incidents.md`.
 
 ## Constraints
 
 - MUST NOT perform mutating actions before explicit user approval.
 - Task documentation updates MAY be batched within one turn before approval.
 - MUST run `task plan approve` then `task start-ready` as `Step 1 -> wait -> Step 2` (never parallel).
+- In direct mode, `finish` auto-creates the deterministic close commit by default; use `--no-close-commit` only for explicit manual handling.
 - MUST stop and request re-approval on material drift.
 - Do not use worktrees in direct mode.
 - Do not perform `branch_pr`-only operations.

package/bin/agentplane.js

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
+import { getWatchedRuntimePathsForPackage } from "./runtime-watch.js";
+import { classifyStaleDistPolicy } from "./stale-dist-policy.js";
+import { isPathInside, resolveFrameworkBinaryContext } from "./runtime-context.js";
 
 async function exists(p) {
   try {
@@ -14,15 +18,12 @@ async function exists(p) {
 }
 
 async function maybeWarnGlobalBinaryInRepoCheckout() {
-  const cwd = process.cwd();
-  const repoCli = path.join(cwd, "packages", "agentplane", "src", "cli.ts");
-  const repoBin = path.join(cwd, "packages", "agentplane", "bin", "agentplane.js");
-  if (!(await exists(repoCli)) || !(await exists(repoBin))) return;
-
   const thisBin = fileURLToPath(import.meta.url);
+  const context = resolveFrameworkBinaryContext({ cwd: process.cwd(), thisBin });
+  if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return;
+
   const normalizedThis = path.resolve(thisBin);
-  const normalizedRepo = path.resolve(repoBin);
-  if (normalizedThis === normalizedRepo) return;
+  const normalizedRepo = path.resolve(context.checkout.repoBin);
 
   process.stderr.write(
     "warning: running global agentplane binary inside repository checkout.\n" +
@@ -36,6 +37,77 @@ async function maybeWarnGlobalBinaryInRepoCheckout() {
   );
 }
 
+function shouldUseGlobalBinaryInFramework() {
+  return (process.env.AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK ?? "").trim() === "1";
+}
+
+function isRepoLocalHandoffInvocation() {
+  return (process.env.AGENTPLANE_REPO_LOCAL_HANDOFF ?? "").trim() === "1";
+}
+
+function inferRuntimeMode(context) {
+  if (context.inFrameworkCheckout && context.isRepoLocalRuntime) {
+    return isRepoLocalHandoffInvocation() ? "repo-local-handoff" : "repo-local";
+  }
+  if (context.inFrameworkCheckout && shouldUseGlobalBinaryInFramework()) {
+    return "global-forced-in-framework";
+  }
+  if (context.inFrameworkCheckout) {
+    return "global-in-framework";
+  }
+  return "global-installed";
+}
+
+function primeRuntimeEnv(context) {
+  process.env.AGENTPLANE_RUNTIME_ACTIVE_BIN = context.thisBin;
+  process.env.AGENTPLANE_RUNTIME_MODE = inferRuntimeMode(context);
+  if (!isRepoLocalHandoffInvocation()) {
+    delete process.env.AGENTPLANE_RUNTIME_HANDOFF_FROM;
+  }
+}
+
+function handoffToRepoLocalBinary(context) {
+  const repoBin = context.checkout?.repoBin;
+  if (!repoBin) return false;
+
+  process.stderr.write(
+    `info: detected framework checkout; delegating to repo-local binary: ${repoBin}\n`,
+  );
+
+  const result = spawnSync(process.execPath, [repoBin, ...process.argv.slice(2)], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      AGENTPLANE_REPO_LOCAL_HANDOFF: "1",
+      AGENTPLANE_RUNTIME_MODE: "repo-local-handoff",
+      AGENTPLANE_RUNTIME_ACTIVE_BIN: path.resolve(repoBin),
+      AGENTPLANE_RUNTIME_HANDOFF_FROM: context.thisBin,
+    },
+  });
+
+  if (result.error) {
+    process.stderr.write(`error: failed to launch repo-local binary: ${result.error.message}\n`);
+    process.exitCode = 2;
+    return true;
+  }
+
+  process.exitCode = result.status ?? (result.signal ? 1 : 0);
+  return true;
+}
+
+function maybeHandoffToRepoLocalBinary() {
+  if (shouldUseGlobalBinaryInFramework() || isRepoLocalHandoffInvocation()) return false;
+
+  const context = resolveFrameworkBinaryContext({
+    cwd: process.cwd(),
+    thisBin: fileURLToPath(import.meta.url),
+  });
+  if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return false;
+
+  return handoffToRepoLocalBinary(context);
+}
+
 function isHooksRunCommitMsgInvocation(argv) {
   const args = argv.slice(2).map((value) => String(value ?? "").trim());
   for (let i = 0; i < args.length; i += 1) {
@@ -45,11 +117,6 @@ function isHooksRunCommitMsgInvocation(argv) {
   return false;
 }
 
-function isPathInside(baseDir, targetPath) {
-  const rel = path.relative(path.resolve(baseDir), path.resolve(targetPath));
-  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-}
-
 async function assertDistUpToDate() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const agentplaneRoot = path.resolve(here, "..");
@@ -74,11 +141,16 @@ async function assertDistUpToDate() {
     {
       name: "agentplane",
       root: agentplaneRoot,
-      watchedPaths: ["src", "bin/agentplane.js", "bin/dist-guard.js"],
+      watchedPaths: getWatchedRuntimePathsForPackage("agentplane"),
     },
   ];
-  if (await exists(path.join(coreRoot, "src")))
-    checks.push({ name: "core", root: coreRoot, watchedPaths: ["src"] });
+  if (await exists(path.join(coreRoot, "src"))) {
+    checks.push({
+      name: "core",
+      root: coreRoot,
+      watchedPaths: getWatchedRuntimePathsForPackage("@agentplaneorg/core"),
+    });
+  }
 
   const staleReasons = [];
   for (const check of checks) {
@@ -104,6 +176,24 @@ async function assertDistUpToDate() {
       return true;
     }
 
+    const commandPolicy = classifyStaleDistPolicy(process.argv);
+    if (commandPolicy.mode === "warn_and_run") {
+      const commandText = process.argv
+        .slice(2)
+        .map((value) => String(value ?? "").trim())
+        .filter(Boolean)
+        .join(" ");
+      process.stderr.write(
+        "warning: allowing read-only diagnostic command to run with a stale repo build inside the framework checkout.\n" +
+          `command: ${commandText || "<unknown>"}\n` +
+          `detected: ${staleReasons.join(", ")}\n` +
+          "rebuild recommended:\n" +
+          "  bun run --filter=@agentplaneorg/core build\n" +
+          "  bun run --filter=agentplane build\n",
+      );
+      return true;
+    }
+
     process.stderr.write(
       "error: refusing to run a stale repo build (manifest/git quick-check failed).\n" +
         "Fix:\n" +
@@ -119,6 +209,14 @@ async function assertDistUpToDate() {
   return true;
 }
 
-await maybeWarnGlobalBinaryInRepoCheckout();
-const ok = isHooksRunCommitMsgInvocation(process.argv) ? true : await assertDistUpToDate();
-if (ok) await import("../dist/cli.js");
+const runtimeContext = resolveFrameworkBinaryContext({
+  cwd: process.cwd(),
+  thisBin: fileURLToPath(import.meta.url),
+});
+primeRuntimeEnv(runtimeContext);
+
+if (!maybeHandoffToRepoLocalBinary()) {
+  await maybeWarnGlobalBinaryInRepoCheckout();
+  const ok = isHooksRunCommitMsgInvocation(process.argv) ? true : await assertDistUpToDate();
+  if (ok) await import("../dist/cli.js");
+}

package/bin/dist-guard.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { readFile, stat } from "node:fs/promises";
+import { collectWatchedRuntimeSnapshot, compareWatchedRuntimeSnapshots } from "./runtime-watch.js";
 
 async function exists(p) {
   try {
@@ -33,12 +34,13 @@ function resolveGitHead(cwd) {
   }
 }
 
-function listGitPaths(cwd, args) {
+function listGitPaths(cwd, args, options = {}) {
+  const trimLines = options.trimLines ?? true;
   try {
     const out = execFileSync("git", args, { cwd, encoding: "utf8" });
     return out
       .split(/\r?\n/u)
-      .map((line) => line.trim())
+      .map((line) => (trimLines ? line.trim() : line))
       .filter(Boolean);
   } catch {
     return [];
@@ -50,14 +52,19 @@ function uniqueSorted(values) {
 }
 
 function workingTreeChangedPaths(cwd, watchedPaths) {
-  const lines = listGitPaths(cwd, [
-    "status",
-    "--porcelain",
-    "--untracked-files=all",
-    "--",
-    ...watchedPaths,
-  ]);
-  return uniqueSorted(lines.map((line) => line.slice(3).trim()).filter(Boolean));
+  const lines = listGitPaths(
+    cwd,
+    ["status", "--porcelain", "--untracked-files=all", "--", ...watchedPaths],
+    { trimLines: false },
+  );
+  return uniqueSorted(
+    lines
+      .map((line) => {
+        const normalized = String(line ?? "");
+        return normalized.length > 3 ? normalized.slice(3).trim() : "";
+      })
+      .filter(Boolean),
+  );
 }
 
 function committedChangedPathsSince(cwd, fromGitHead, watchedPaths) {
@@ -77,6 +84,45 @@ async function fileMtimeMs(p) {
   }
 }
 
+function parseManifestSnapshot(manifest) {
+  if (
+    !Array.isArray(manifest?.watched_runtime_paths) ||
+    !Array.isArray(manifest?.watched_runtime_files) ||
+    typeof manifest?.watched_runtime_snapshot_hash !== "string"
+  ) {
+    return null;
+  }
+
+  const watchedPaths = manifest.watched_runtime_paths.filter((value) => typeof value === "string");
+  const files = manifest.watched_runtime_files
+    .filter(
+      (value) =>
+        value &&
+        typeof value === "object" &&
+        typeof value.path === "string" &&
+        typeof value.sha256 === "string" &&
+        typeof value.size_bytes === "number",
+    )
+    .map((value) => ({
+      path: value.path,
+      sha256: value.sha256,
+      size_bytes: value.size_bytes,
+    }));
+
+  if (
+    watchedPaths.length !== manifest.watched_runtime_paths.length ||
+    files.length !== manifest.watched_runtime_files.length
+  ) {
+    return null;
+  }
+
+  return {
+    watchedPaths,
+    files,
+    snapshotHash: manifest.watched_runtime_snapshot_hash,
+  };
+}
+
 export async function isPackageBuildFresh(packageRoot, options = {}) {
   const watchedPaths = options.watchedPaths ?? ["src"];
   const manifestPath = path.join(packageRoot, "dist", ".build-manifest.json");
@@ -86,6 +132,28 @@ export async function isPackageBuildFresh(packageRoot, options = {}) {
   }
 
   const currentHead = resolveGitHead(packageRoot);
+  const manifestSnapshot = parseManifestSnapshot(manifest);
+  if (manifestSnapshot) {
+    const currentSnapshot = await collectWatchedRuntimeSnapshot(
+      packageRoot,
+      manifestSnapshot.watchedPaths,
+    );
+    const comparison = compareWatchedRuntimeSnapshots(manifestSnapshot, currentSnapshot);
+    if (!comparison.ok) {
+      return {
+        ok: false,
+        reason: "watched_runtime_snapshot_changed",
+        changedPaths: comparison.changedPaths,
+      };
+    }
+
+    if (manifest.git_head && currentHead && manifest.git_head !== currentHead) {
+      return { ok: true, reason: "fresh_after_snapshot_match", changedPaths: [] };
+    }
+
+    return { ok: true, reason: "fresh", changedPaths: [] };
+  }
+
   const changedPaths = uniqueSorted([
     ...committedChangedPathsSince(packageRoot, manifest.git_head, watchedPaths),
     ...workingTreeChangedPaths(packageRoot, watchedPaths),

package/bin/runtime-context.d.ts

@@ -0,0 +1,23 @@
+export type FrameworkCheckout = {
+  repoRoot: string;
+  packageRoot: string;
+  repoBin: string;
+  repoCli: string;
+};
+
+export type FrameworkBinaryContext = {
+  inFrameworkCheckout: boolean;
+  isRepoLocalBinary: boolean;
+  isRepoLocalRuntime: boolean;
+  checkout: FrameworkCheckout | null;
+  thisBin: string;
+};
+
+export function findFrameworkCheckout(startDir: string): FrameworkCheckout | null;
+
+export function isPathInside(baseDir: string, targetPath: string): boolean;
+
+export function resolveFrameworkBinaryContext(options: {
+  cwd: string;
+  thisBin: string;
+}): FrameworkBinaryContext;