agentplane 0.3.2 → 0.3.3

package/assets/AGENTS.md

@@ -195,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.
@@ -31,10 +33,12 @@ 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
 

package/bin/agentplane.js

@@ -4,7 +4,9 @@ import path from "node:path";
 import { stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
-import { resolveFrameworkBinaryContext } from "./runtime-context.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 {
@@ -43,6 +45,27 @@ 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;
@@ -57,6 +80,9 @@ function handoffToRepoLocalBinary(context) {
     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,
     },
   });
 
@@ -91,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, "..");
@@ -120,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) {
@@ -150,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" +
@@ -165,6 +209,12 @@ async function assertDistUpToDate() {
   return true;
 }
 
+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();

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

@@ -8,12 +8,15 @@ export type FrameworkCheckout = {
 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;

package/bin/runtime-context.js

@@ -21,6 +21,7 @@ import path from "node:path";
  * @typedef {{
  *   inFrameworkCheckout: boolean;
  *   isRepoLocalBinary: boolean;
+ *   isRepoLocalRuntime: boolean;
  *   checkout: FrameworkCheckout | null;
  *   thisBin: string;
  * }} FrameworkBinaryContext
@@ -55,6 +56,16 @@ export function findFrameworkCheckout(startDir) {
   }
 }
 
+/**
+ * @param {string} baseDir
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function isPathInside(baseDir, targetPath) {
+  const rel = path.relative(path.resolve(baseDir), path.resolve(targetPath));
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
 /**
  * @param {FrameworkBinaryContextOptions} options
  * @returns {FrameworkBinaryContext}
@@ -67,6 +78,7 @@ export function resolveFrameworkBinaryContext(options) {
     return {
       inFrameworkCheckout: false,
       isRepoLocalBinary: false,
+      isRepoLocalRuntime: false,
       checkout: null,
       thisBin,
     };
@@ -75,6 +87,7 @@ export function resolveFrameworkBinaryContext(options) {
   return {
     inFrameworkCheckout: true,
     isRepoLocalBinary: path.resolve(checkout.repoBin) === thisBin,
+    isRepoLocalRuntime: isPathInside(checkout.packageRoot, thisBin),
     checkout,
     thisBin,
   };

package/bin/runtime-watch.d.ts

@@ -0,0 +1,26 @@
+export type WatchedRuntimeSnapshotFile = {
+  path: string;
+  sha256: string;
+  size_bytes: number;
+};
+
+export type WatchedRuntimeSnapshot = {
+  watchedPaths: string[];
+  files: WatchedRuntimeSnapshotFile[];
+  snapshotHash: string;
+};
+
+export type WatchedRuntimeSnapshotComparison = {
+  ok: boolean;
+  changedPaths: string[];
+};
+
+export function getWatchedRuntimePathsForPackage(packageName: string): string[];
+export function collectWatchedRuntimeSnapshot(
+  packageDir: string,
+  watchedPaths: string[],
+): Promise<WatchedRuntimeSnapshot>;
+export function compareWatchedRuntimeSnapshots(
+  recordedSnapshot: WatchedRuntimeSnapshot,
+  currentSnapshot: WatchedRuntimeSnapshot,
+): WatchedRuntimeSnapshotComparison;