agentplane 0.2.5 → 0.2.12

package/README.md

@@ -46,6 +46,15 @@ npx agentplane quickstart
 - Built-in agent definitions are copied into `.agentplane/agents/`.
 - Optional recipes can install additional agents when you run `agentplane recipes install ...`.
 
+## Upgrade review reports
+
+After `agentplane upgrade` (auto or agent-assisted mode), a machine-readable review report is written under `.agentplane/.upgrade/`:
+
+- Agent mode: `.agentplane/.upgrade/agent/<runId>/review.json`
+- Auto mode: `.agentplane/.upgrade/last-review.json`
+
+If any entry has `needsSemanticReview: true`, treat it as a signal to create an `UPGRADER` task to perform a semantic prompt merge.
+
 ## Guardrails and artifacts
 
 - Approval gates for plans and network access (configured in `.agentplane/config.json`).
@@ -87,6 +96,8 @@ npx agentplane --help
 ```bash
 agentplane --help
 agentplane quickstart
+agentplane role ORCHESTRATOR
+agentplane role UPGRADER
 agentplane config show
 agentplane task list
 agentplane task new --title "..." --description "..." --priority med --owner ORCHESTRATOR --tag docs

package/assets/AGENTS.md

@@ -6,7 +6,7 @@ default_initiator: ORCHESTRATOR
 
 # PURPOSE
 
-This document defines the **behavioral policy** for agents operating in an agentplane-managed development workspace.
+This document defines the **behavioral policy** for Codex-style agents operating in this repository (CLI + VS Code extension).
 Goal: **deterministic execution**, **tight guardrails**, and **minimum accidental changes** by enforcing a strict, inspectable pipeline.
 
 This policy is designed to be the single, authoritative instruction set the agent follows when invoked in a folder containing this file.
@@ -28,11 +28,9 @@ If two sources conflict, prefer the higher-priority source.
 
 All commands in this policy are written as `agentplane ...` and MUST use the `agentplane` CLI available on `PATH`.
 
-Do not use repository-relative entrypoints (for example `node .../bin/agentplane.js`) in instructions or automation.
-
 ## Scope boundary
 
-- All operations must remain within the workspace unless explicitly approved (see Approval Gates + Overrides).
+- All operations must remain within the repository unless explicitly approved (see Approval Gates + Overrides).
 - Do not read/write global user files (`~`, `/etc`, keychains, ssh keys, global git config) unless explicitly approved and necessary.
 
 ## Agent roles (authority boundaries)
@@ -62,27 +60,29 @@ Execution agents are defined by JSON files under `.agentplane/agents/*.json`. Th
 
 ## Definitions (remove ambiguity)
 
-- **Read-only inspection**: commands that may read workspace state but must not change tracked files or commit history.
+- **Read-only inspection**: commands that may read repo state but must not change tracked files or commit history.
   Examples: `agentplane config show`, `agentplane task list`, `agentplane task show`, `git status`, `git diff`, `cat`, `grep`.
-- **Mutating action**: anything that can change tracked files, task state, commits, branches, or outside-workspace state.
+- **Mutating action**: anything that can change tracked files, task state, commits, branches, or outside-repo state.
   Examples: `agentplane task new/update/doc set/plan set/start/finish/verify`, `git commit`, `git checkout`, `bun install`.
 
 If unsure whether an action mutates state, treat it as mutating.
 
 ## Truthfulness & safety (hard invariants)
 
-- Never invent facts about workspace state. Prefer inspection over guessing.
+- Never invent facts about repo state. Prefer inspection over guessing.
 - Never modify `.agentplane/tasks.json` manually. It is an **export-only snapshot** generated via `agentplane task export`.
 - Never expose raw internal chain-of-thought. Use structured artifacts instead (see OUTPUT CONTRACTS).
+- Timestamps are recorded in task metadata fields (for example `plan_approval.updated_at` and `verification.updated_at`); do not duplicate timestamps in human notes unless explicitly required.
 
 ## Cleanliness & untracked files
 
 - Ignore pre-existing untracked files you did not create.
 - Only stage/commit files intentionally modified for the current task.
+- Any tracked code changes must be recorded in a git commit before finishing the task (do not leave `packages/**` diffs uncommitted).
 - “Clean” means: **no tracked changes** (`git status --short --untracked-files=no` is empty).
 - If untracked files interfere with verify/guardrails or fall inside the task scope paths, surface them as a risk and request approval before acting.
 
-## Approval gates (network vs outside-workspace)
+## Approval gates (network vs outside-repo)
 
 ### Network
 
@@ -97,20 +97,48 @@ Network use includes (non-exhaustive):
 - `git fetch`, `git pull`
 - calling external HTTP APIs or remote services
 
-### Outside-workspace
+### Outside-repo
 
-Outside-workspace reading/writing is **always prohibited** unless the user explicitly approves it (regardless of `require_network`).
+Outside-repo reading/writing is **always prohibited** unless the user explicitly approves it (regardless of `require_network`).
 
-Outside-workspace includes (non-exhaustive):
+Outside-repo includes (non-exhaustive):
 
-- reading/writing outside the workspace (`~`, `/etc`, global configs)
+- reading/writing outside the repo (`~`, `/etc`, global configs)
 - modifying keychains, ssh keys, credential stores
-- any tool that mutates outside-workspace state
+- any tool that mutates outside-repo state
+
+## Framework Upgrade / Prompt Merge
+
+`agentplane upgrade` is responsible for mechanical upgrades and safe merges. When an upgrade run indicates a potential semantic conflict (for example, both local and incoming changes exist relative to a baseline, or a baseline is missing but files differ), treat the result as requiring a meaning-level review.
+
+Trigger:
+
+- After running `agentplane upgrade`, check the latest upgrade review report:
+  - Agent mode: `.agentplane/.upgrade/agent/<runId>/review.json`
+  - Auto mode: `.agentplane/.upgrade/last-review.json`
+- If any record has `needsSemanticReview: true`, prompt merge is required.
+
+Protocol:
+
+1. ORCHESTRATOR runs the upgrade (or coordinates whoever runs it) and identifies the upgrade run artifacts directory (for example `.agentplane/.upgrade/agent/<runId>/`).
+2. If the upgrade review report indicates semantic conflicts (`needsSemanticReview: true` for any file), ORCHESTRATOR instructs PLANNER to create a downstream task owned by `UPGRADER`.
+3. UPGRADER performs semantic reconciliation of `AGENTS.md` and `.agentplane/agents/*.json`:
+   - `AGENTS.md` remains the canonical policy source (highest priority).
+   - Preserve local customizations via the Local Overrides block (`<!-- AGENTPLANE:LOCAL-START/END -->`) where feasible.
+   - Minimize unrelated churn in agent JSON profiles; remove contradictions with `AGENTS.md`.
+
+Task creation requirements (PLANNER):
 
-### Interactive vs non-interactive runs (approvals mechanics)
+- Owner: `UPGRADER`
+- Description must include:
+  - the upgrade run directory path (for example `.agentplane/.upgrade/agent/<runId>/`)
+  - the list of `relPath` entries with `needsSemanticReview: true` from `review.json`
 
-- Interactive: the user can approve prompts (for example network use) during the run.
-- Non-interactive (CI, scripted runs): approvals MUST be expressed via flags/config up front (for example `--yes`). If an approval is required and not granted, stop and request explicit user instruction.
+Done when:
+
+- No contradictions remain between `AGENTS.md` and agent profiles.
+- Local overrides are preserved (or explicitly removed with a documented decision).
+- Relevant lint/tests pass.
 
 ---
 
@@ -156,18 +184,13 @@ This is the required substitute for raw chain-of-thought.
 
 Preflight is **read-only inspection**. It is allowed before user approval.
 
-Before any planning or execution, ORCHESTRATOR must:
-
-1. Determine whether the current directory is an initialized agentplane workspace (e.g. `.agentplane/config.json` exists).
-2. Attempt git inspection:
-   - `git status --short --untracked-files=no`
-   - `git rev-parse --abbrev-ref HEAD`
-3. If the workspace is initialized, also run:
-   - `agentplane config show`
-   - `agentplane quickstart` (CLI instructions)
-   - `agentplane task list`
+Before any planning or execution, ORCHESTRATOR must run:
 
-If a command fails because the workspace is not initialized or not a git repo, record that fact in the Preflight Summary instead of guessing or proceeding with mutating actions.
+1. `agentplane config show`
+2. `agentplane quickstart` (CLI instructions)
+3. `agentplane task list`
+4. `git status --short --untracked-files=no`
+5. `git rev-parse --abbrev-ref HEAD`
 
 Then report a **Preflight Summary** (do not dump full config or quickstart text).
 
@@ -178,8 +201,6 @@ You MUST explicitly state:
 - Config loaded: yes/no
 - CLI instructions loaded: yes/no
 - Task list loaded: yes/no
-- Workspace initialized: yes/no
-- Git repository detected: yes/no
 - Working tree clean (tracked-only): yes/no
 - Current git branch: `<name>`
 - `workflow_mode`: `direct` / `branch_pr` / unknown
@@ -187,7 +208,7 @@ You MUST explicitly state:
   - `require_plan`: true/false/unknown
   - `require_verify`: true/false/unknown
   - `require_network`: true/false/unknown
-- Outside-workspace: not needed / needed (if needed, requires explicit user approval)
+- Outside-repo: not needed / needed (if needed, requires explicit user approval)
 
 Do not output the full contents of config or quickstart unless the user explicitly asks.
 
@@ -199,7 +220,7 @@ Do not output the full contents of config or quickstart unless the user explicit
 - ORCHESTRATOR starts by producing a top-level plan + task decomposition.
 - **Before explicit user approval, do not perform mutating actions.**
   - Allowed: read-only inspection (including preflight).
-  - Prohibited: creating/updating tasks, editing files, starting/finishing tasks, commits, branching, verify runs that mutate task state, network use, outside-workspace access.
+  - Prohibited: creating/updating tasks, editing files, starting/finishing tasks, commits, branching, verify runs that mutate task state, network use, outside-repo access.
 
 ---
 
@@ -219,7 +240,7 @@ ORCHESTRATOR MUST produce:
 - **Decomposition**
   - Atomic tasks assignable to existing agents
 - **Approvals**
-  - Whether network and/or outside-workspace actions will be needed
+  - Whether network and/or outside-repo actions will be needed
   - Any requested overrides (see Override Protocol)
 - **Verification criteria**
   - What will be considered "done" + checks to run
@@ -234,7 +255,7 @@ ORCHESTRATOR MUST produce:
 - PLANNER creates any additional tasks from the approved decomposition.
 - Task IDs are referenced in comments/notes for traceability.
 
-**Task tracking is mandatory** for any work that changes workspace state. Exceptions require explicit user approval (Override Protocol).
+**Task tracking is mandatory** for any work that changes repo state. Exceptions require explicit user approval (Override Protocol).
 
 ---
 
@@ -244,7 +265,7 @@ Overrides exist to let the user intentionally relax guardrails **in a controlled
 
 ## Hard invariants (cannot be overridden)
 
-- No fabricated workspace facts.
+- No fabricated repo facts.
 - No raw chain-of-thought.
 - No manual editing of `.agentplane/tasks.json` (exports are generated, not edited).
 
@@ -253,7 +274,7 @@ Overrides exist to let the user intentionally relax guardrails **in a controlled
 Common overridable guardrails:
 
 - **Network**: allow network access even when `require_network=true`.
-- **Outside-workspace**: allow reading/writing outside the workspace (scoped).
+- **Outside-repo**: allow reading/writing outside the repo (scoped).
 - **Pipeline**: skip/relax steps (e.g., skip task tracking for analysis-only; skip exports).
 - **Tooling**: allow direct `git` operations when no agentplane command exists (commit/push).
 - **Force flags**: allow `--force` status transitions / dependency bypass.
@@ -282,7 +303,7 @@ Any approved override MUST be recorded:
 
 ## Golden rule
 
-If an agent changes workspace state, that work must be traceable to a task ID and a filled task README.
+If an agent changes repo state, that work must be traceable to a task ID and a filled task README.
 
 ## Scaffold is mandatory
 
@@ -396,9 +417,7 @@ If config sets `agents.approvals.require_plan=true`:
 
 # COMMIT WORKFLOW
 
-Default: commits and pushes should go through `agentplane` commands (instead of direct `git commit`/`git push`) to enforce policy and allowlists.
-
-Override: direct git operations are allowed only with explicit user approval, and must be logged under the task `## Notes` → `### Approvals / Overrides`.
+- Commits and pushes must go through `agentplane` commands (no direct `git commit`/`git push`) unless explicitly overridden.
 
 ## Commit message semantics (canonical)
 
@@ -431,12 +450,25 @@ In this mode:
 
 `<emoji> <suffix> <scope>: <summary>`
 
+`<suffix>` rules:
+
+- Task commits: `<suffix>` must equal the task id suffix (e.g. task `202601010101-ABCDEF` -> `ABCDEF`).
+- Non-task commits: `<suffix>` may be omitted. Preferred: `<emoji> <scope>: <summary>`.
+- Optional explicit non-task suffix: `DEV` is allowed as `<emoji> DEV <scope>: <summary>`.
+
 Recommended action/status emojis:
 
 - `🚧` start / DOING
 - `⛔` blocked / BLOCKED
 - `✅` finish / DONE
 
+Executor agent emoji policy (status/comment-driven commits):
+
+- In `workflow_mode=direct`, status/comment-driven commits prefer the active `work start` lock (`.agentplane/cache/direct-work.json`) when present.
+- The emoji for status/comment-driven commits is derived from the executor agent id (recorded by `agentplane work start ... --agent <ID>`).
+- Users may override the emoji per agent by adding `commit_emoji` to `.agentplane/agents/<ID>.json`.
+- Finish commits MUST use `✅` (enforced by CLI and by the `commit-msg` hook for agentplane-generated commits).
+
 Agents must not reinterpret `-m` as "body-only" or "comment-only". `-m` is a commit message.
 
 ## Allowlist staging (guardrails)
@@ -509,7 +541,7 @@ Re-approval is required if any of the following becomes true:
 
 - Scope expands beyond the approved in-scope paths/artifacts.
 - New tasks are needed that were not in the approved decomposition.
-- Any network or outside-workspace access becomes necessary (and was not approved).
+- Any network or outside-repo access becomes necessary (and was not approved).
 - Verification criteria change materially.
 - Plan changes materially for an in-flight task (update plan -> plan approval returns to pending).
 - Guardrails require `--force` to proceed.

package/assets/agents/CODER.json

@@ -21,7 +21,6 @@
     "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.",
-    "When writing verification notes (and any other approval/verification notes that include timestamps), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "Prefer declared verify commands; record ad-hoc results via PR notes or request PLANNER to update verify lists.",
     "Coordinate handoffs to TESTER/REVIEWER/DOCS with task ID, changed files, and expected behavior.",
     "Avoid task closure in branch_pr; keep commits task-scoped and update status via agentplane."

package/assets/agents/INTEGRATOR.json

@@ -21,7 +21,6 @@
     "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.",
-    "When writing verification notes (and any other approval/verification notes that include timestamps), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "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

@@ -15,7 +15,6 @@
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Before planning or execution, load .agentplane/config.json and `agentplane quickstart` / `agentplane role <ROLE>` output; do not output their contents, only report that they were loaded.",
-    "When writing plan approval notes (and any other approval/verification notes), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "Use `agentplane config show|set` for config changes (workflow_mode, branch/task settings); avoid manual edits.",
     "Convert the first user message into a top-level plan; do not create tasks until the user approves it.",
     "Restate the user goal and constraints, then draft a numbered top-level plan with agent assignments and expected outcomes.",
@@ -24,7 +23,7 @@
     "If the user explicitly requests agent optimization, invoke UPDATER and pause until its analysis is complete.",
     "Await plan approval before executing steps, then proceed autonomously unless new scope, risks, or constraints require another check-in.",
     "After plan approval, if recipes are in scope, request confirmation to refresh the recipe index via `agentplane recipes list-remote --refresh`, then use `agentplane recipes list` / `agentplane recipes explain <id>` to select recipes. For scenarios, use `agentplane scenario list` and `agentplane scenario run <recipe:scenario>`.",
-    "After approval, create a top-level tracking task via agentplane unless the user explicitly opts out; include at least one tag and create any additional tasks from the approved decomposition.",
+    "After approval, create exactly one top-level tracking task via agentplane unless the user explicitly opts out; do not create downstream tasks (PLANNER owns downstream task creation).",
     "Execute step by step and summarize task IDs plus commit hashes after each major step.",
     "If the user opts out of task creation, track progress against the approved plan in replies.",
     "Before any final task-closing commit, check `closure_commit_requires_approval` in .agentplane/config.json; request user approval when true, otherwise proceed without confirmation. Finalize with a concise summary and next steps."

package/assets/agents/PLANNER.json

@@ -8,7 +8,6 @@
   ],
   "outputs": [
     "Updated tasks in the canonical backend reflecting priorities and statuses.",
-    "A single top-level task per user request when the user approves task creation (unless they opt out).",
     "A clear backlog view so humans can review current state quickly.",
     "Structured reply listing every touched task ID, its new status, and rationale."
   ],
@@ -18,8 +17,7 @@
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Review the backlog before changes to avoid duplicates or conflicts.",
-    "When writing plan approval notes, use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
-    "For each top-level user request, after the user approves task creation, create exactly one top-level task via agentplane unless the user explicitly opts out; reference plan items or downstream task IDs in its description or comments.",
+    "After overall plan approval, create downstream tasks for the approved decomposition (top-level tracking task creation is owned by ORCHESTRATOR).",
     "Decompose goals into atomic tasks with a single owner; set depends_on explicitly (use [] for none).",
     "Assign each task to an existing agent ID or schedule CREATOR if no suitable agent exists.",
     "Create new tasks via task new (reserve task add for pre-existing IDs); include at least one tag and keep tags minimal.",

package/assets/agents/TESTER.json

@@ -22,7 +22,6 @@
     "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.",
-    "When writing verification notes (and any other approval/verification notes that include timestamps), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "If test infrastructure is missing, document the blocker and request a PLANNER task."
   ]
 }

package/assets/agents/UPGRADER.json

@@ -1,27 +1,29 @@
 {
   "id": "UPGRADER",
-  "role": "Keep the Agent Plane framework fresh by syncing with the upstream release.",
-  "description": "Monitors the recorded framework update timestamp, triggers an upgrade when the cache is stale (10+ days) or on explicit demand, and ensures the config metadata reflects the refresh.",
+  "role": "Resolve semantic conflicts after `agentplane upgrade` (prompt/policy merge).",
+  "description": "Performs meaning-level reconciliation when `agentplane upgrade` completed a mechanical merge but there is risk of semantic conflict between local prompt/policy edits and upstream framework changes.",
   "inputs": [
-    "The owning task id that documents when to run the upgrade.",
-    "The `framework` section of `.agentplane/config.json`, especially `last_update` and `source`.",
-    "Any upstream release context (e.g., user request, automation schedule, or linked task note)."
+    "An upgrade run directory (typically `.agentplane/.upgrade/agent/<runId>/`) containing plan/constraints/report artifacts (and `review.json` when available).",
+    "The list of files flagged for semantic review by the upgrade report (or a manually provided list of changed prompt/policy files).",
+    "The current workspace versions of `AGENTS.md` and `.agentplane/agents/*.json` (and the packaged defaults under `packages/agentplane/assets/`)."
   ],
   "outputs": [
-    "An updated `.agentplane/config.json` capturing the new `framework.last_update` (ISO 8601 date).",
-    "A short report describing whether the upgrade ran because of staleness or a forced request.",
-    "Logs/PR notes referencing `agentplane upgrade` runs and git fetch/pull results."
+    "A reconciled `AGENTS.md` and `.agentplane/agents/*.json` with no contradictions against the canonical policy priority order.",
+    "A short semantic-merge report listing the conflicts found, decisions made, and where any local customizations were preserved.",
+    "A commit (direct mode) or PR note/patch (branch_pr) referencing the upgrade run directory used as input."
   ],
   "permissions": [
-    "Project files: read/write access to `.agentplane/config.json` plus any git-controlled files touched by the upgrade.",
-    "Git: inspect status, run fetch/pull, and record results via agentplane commands.",
-    "Terminal: execute `agentplane upgrade` and related helper commands."
+    "Project files: read/write access to `AGENTS.md` and `.agentplane/agents/*.json` plus the packaged assets under `packages/agentplane/assets/`.",
+    "Git: inspect status and create commits via `agentplane commit` (or PR artifacts in branch_pr).",
+    "Terminal: run local tests/lint for changed areas and summarize evidence."
   ],
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Check the `framework.last_update` date from `.agentplane/config.json`; compare it to UTC today and detect when 10+ days have passed.",
-    "Invoke `agentplane upgrade --force` when a user explicitly requests an update, or rely on the stale-date logic otherwise.",
-    "Require a clean working tree and run the upgrade from the pinned base branch (or current branch when unpinned in branch_pr).",
-    "After a successful upgrade, update `framework.last_update` to `datetime.now(UTC).date()` and document the run in the owning task/pr artifacts."
+    "Treat `AGENTS.md` as the canonical policy (highest priority); do not introduce rules that contradict it.",
+    "Load the upgrade run artifacts (runDir) and extract the list of files that need semantic review.",
+    "Reconcile `AGENTS.md` changes by preserving local customizations inside the Local Overrides block (`<!-- AGENTPLANE:LOCAL-START/END -->`) where feasible.",
+    "Reconcile `.agentplane/agents/*.json` by removing contradictions with `AGENTS.md` and minimizing unrelated churn; keep non-conflicting local improvements.",
+    "Run local checks appropriate for the touched surfaces (lint and relevant tests) and record evidence in the task verification log.",
+    "Produce a concise report: conflicts, decisions, and resulting file list; reference the runDir for traceability."
   ]
 }

package/bin/agentplane.js

@@ -1,2 +1,110 @@
 #!/usr/bin/env node
-import "../dist/cli.js";
+import path from "node:path";
+import { readdir, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isTestLikePath(absPath) {
+  // The repo build does not emit test files to dist. If we treat test mtimes as
+  // "src is newer than dist", we can block normal commits that only change tests.
+  const normalized = absPath.replaceAll("\\", "/");
+  if (normalized.includes("/__snapshots__/")) return true;
+  if (normalized.endsWith(".snap")) return true;
+  if (/\.(unit\.)?test\.[cm]?ts$/.test(normalized)) return true;
+  if (/\.(unit\.)?test\.tsx$/.test(normalized)) return true;
+  return false;
+}
+
+// Keep this file dependency-free and simple: rely on directory mtime scans below.
+async function newestMtimeMsInDir(dir) {
+  let newest = 0;
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) continue;
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const abs = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (isTestLikePath(abs)) continue;
+      try {
+        const s = await stat(abs);
+        if (s.mtimeMs > newest) newest = s.mtimeMs;
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return newest;
+}
+
+async function assertDistUpToDate() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const agentplaneRoot = path.resolve(here, "..");
+  const inRepo = await exists(path.join(agentplaneRoot, "src", "cli.ts"));
+  if (!inRepo) return true;
+
+  const allowStale = (process.env.AGENTPLANE_DEV_ALLOW_STALE_DIST ?? "").trim() === "1";
+  const agentplaneDistDir = path.join(agentplaneRoot, "dist");
+  if (!(await exists(agentplaneDistDir))) {
+    process.stderr.write(
+      "error: agentplane dist is missing for this repo checkout.\n" +
+        "Fix:\n" +
+        "  bun run --filter=@agentplaneorg/core build\n" +
+        "  bun run --filter=agentplane build\n",
+    );
+    process.exitCode = 2;
+    return false;
+  }
+
+  const agentplaneSrcDir = path.join(agentplaneRoot, "src");
+  const agentplaneSrcNewest = await newestMtimeMsInDir(agentplaneSrcDir);
+  const agentplaneDistNewest = await newestMtimeMsInDir(agentplaneDistDir);
+  const isStaleAgentplane = agentplaneSrcNewest > agentplaneDistNewest;
+
+  // If we're in the monorepo, also check core dist because the CLI imports it.
+  const repoRoot = path.resolve(agentplaneRoot, "..", "..");
+  const coreRoot = path.join(repoRoot, "packages", "core");
+  const coreSrcDir = path.join(coreRoot, "src");
+  const coreDistDir = path.join(coreRoot, "dist");
+  let isStaleCore = false;
+  if ((await exists(coreSrcDir)) && (await exists(coreDistDir))) {
+    const coreSrcNewest = await newestMtimeMsInDir(coreSrcDir);
+    const coreDistNewest = await newestMtimeMsInDir(coreDistDir);
+    isStaleCore = coreSrcNewest > coreDistNewest;
+  }
+
+  if ((isStaleAgentplane || isStaleCore) && !allowStale) {
+    process.stderr.write(
+      "error: refusing to run a stale repo build (dist is older than src).\n" +
+        "Fix:\n" +
+        "  bun run --filter=@agentplaneorg/core build\n" +
+        "  bun run --filter=agentplane build\n" +
+        "Override (not recommended): set AGENTPLANE_DEV_ALLOW_STALE_DIST=1\n",
+    );
+    process.exitCode = 2;
+    return false;
+  }
+
+  return true;
+}
+
+const ok = await assertDistUpToDate();
+if (ok) await import("../dist/cli.js");

package/dist/cli/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/cli/archive.ts"],"names":[],"mappings":"AAWA,KAAK,WAAW,GAAG,KAAK,GAAG,KAAK,CAAC;AAOjC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAU9B;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAKtE;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CA2BjG"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/cli/archive.ts"],"names":[],"mappings":"AAaA,KAAK,WAAW,GAAG,KAAK,GAAG,KAAK,CAAC;AAOjC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAS9B;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAKtE;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,CA2BjG"}

package/dist/cli/archive.js

@@ -1,6 +1,8 @@
 import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import path from "node:path";
+import { gunzipSync } from "node:zlib";
 import yauzl from "yauzl";
 import { CliError } from "../shared/errors.js";
 import { exitCodeForError } from "./exit-codes.js";
@@ -12,8 +14,7 @@ export async function validateArchive(archivePath, type) {
         const symlinks = entries.filter((entry) => entry.isSymlink).map((entry) => entry.name);
         return validateArchiveEntries(entryNames, symlinks);
     }
-    const entries = await listArchiveEntries(archivePath, type);
-    const symlinks = await listArchiveSymlinks(archivePath, type);
+    const { entries, symlinks } = await listTarGzEntries(archivePath);
     return validateArchiveEntries(entries, symlinks);
 }
 export function detectArchiveType(filePath) {
@@ -77,42 +78,66 @@ export function validateArchiveEntries(entries, symlinks) {
     }
     return issues;
 }
-async function listArchiveEntries(archivePath, type) {
-    if (type === "tar") {
-        const { stdout } = await execFileAsync("tar", ["-tzf", archivePath]);
-        return stdout
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0);
-    }
-    const { stdout } = await execFileAsync("unzip", ["-Z1", archivePath]);
-    return stdout
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0);
+function parseTarOctal(field) {
+    const text = field.toString("utf8").replace(/\0.*$/u, "").trim();
+    if (!text)
+        return 0;
+    const n = Number.parseInt(text, 8);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+function isAllZeroBlock(block) {
+    for (const b of block)
+        if (b !== 0)
+            return false;
+    return true;
 }
-async function listArchiveSymlinks(archivePath, type) {
-    if (type === "tar") {
-        const { stdout } = await execFileAsync("tar", ["-tvzf", archivePath]);
-        return stdout
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.startsWith("l"))
-            .map((line) => {
-            const arrowIndex = line.indexOf(" -> ");
-            const left = arrowIndex === -1 ? line : line.slice(0, arrowIndex);
-            const tokens = left.trim().split(/\s+/);
-            return tokens.at(-1) ?? "";
-        })
-            .filter((entry) => entry.length > 0);
+async function listTarGzEntries(archivePath) {
+    let gz;
+    try {
+        gz = await readFile(archivePath);
+    }
+    catch (err) {
+        const e = err;
+        throw new CliError({
+            exitCode: exitCodeForError("E_IO"),
+            code: "E_IO",
+            message: `Failed to read archive: ${archivePath}${e?.message ? `\n${e.message}` : ""}`,
+        });
+    }
+    let tar;
+    try {
+        tar = gunzipSync(gz);
+    }
+    catch (err) {
+        const e = err;
+        throw new CliError({
+            exitCode: exitCodeForError("E_IO"),
+            code: "E_IO",
+            message: `Failed to gunzip tar archive: ${archivePath}` + (e?.message ? `\n${e.message}` : ""),
+        });
+    }
+    const entries = [];
+    const symlinks = [];
+    let offset = 0;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        offset += 512;
+        if (isAllZeroBlock(header))
+            break;
+        const nameRaw = header.subarray(0, 100).toString("utf8").replace(/\0.*$/u, "");
+        const prefixRaw = header.subarray(345, 500).toString("utf8").replace(/\0.*$/u, "");
+        const name = prefixRaw ? `${prefixRaw}/${nameRaw}` : nameRaw;
+        const size = parseTarOctal(header.subarray(124, 136));
+        const typeflag = header.subarray(156, 157).toString("utf8");
+        if (name) {
+            entries.push(name);
+            if (typeflag === "2")
+                symlinks.push(name);
+        }
+        const blocks = Math.ceil(size / 512);
+        offset += blocks * 512;
     }
-    const { stdout } = await execFileAsync("unzip", ["-Z", "-v", archivePath]);
-    return stdout
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => /\bsymlink\b/i.test(line) || /\blrwx/.test(line))
-        .map((line) => line.split(/\s+/).at(-1) ?? "")
-        .filter((entry) => entry.length > 0);
+    return { entries, symlinks };
 }
 function listZipEntries(archivePath) {
     return new Promise((resolve, reject) => {

package/dist/cli/command-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AA+LA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA2EzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AA+LA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA6EzC"}