superdev-cli 0.2.0 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Superdev - tell it what you want to build, and it keeps the product map, documentation, decisions and status in step while specialist providers do the specialist work.",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "homepage": "https://github.com/superdev-ai/superdev"
   },
   "plugins": [
@@ -13,7 +13,7 @@
       "name": "superdev",
       "source": "./",
       "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence - plus a self-contained visual dashboard. Routes specialist work to external providers and reports their readiness truthfully.",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "author": {
         "name": "Rahul Retnan"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence, plus a self-contained visual dashboard. Routes specialist work to external providers and reports their readiness truthfully.",
   "author": {
     "name": "Rahul Retnan"
@@ -16,6 +16,6 @@
   "homepage": "https://github.com/superdev-ai/superdev",
   "repository": "https://github.com/superdev-ai/superdev",
   "requires": {
-    "cli": "0.2.0"
+    "cli": "0.3.0"
   }
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence, plus a self-contained visual dashboard.",
   "author": {
     "name": "Rahul Retnan"
@@ -22,6 +22,6 @@
   "homepage": "https://github.com/superdev-ai/superdev",
   "repository": "https://github.com/superdev-ai/superdev",
   "requires": {
-    "cli": "0.2.0"
+    "cli": "0.3.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Local-first product-building control system for humans and coding agents.",
   "author": "Rahul Retnan",

package/src/cli/render.mjs

@@ -317,6 +317,10 @@ export function renderTaskDetail(detail) {
       ["Priority", status(task.priority ?? "normal")],
       ["Feature", feature ? `${feature.id} ${feature.name}` : task.feature_id],
       ["Parent", task.parent_task_id],
+      // A superseded task that does not say what replaced it leaves anybody who
+      // found the old identifier, in a commit message or a branch name, with
+      // nowhere to go.
+      ["Merged into", task.superseded_by],
       ["Estimate", task.estimate],
       ["Due", task.due_at ? shortDate(task.due_at) : null],
       ["Blocked because", task.block_reason],

package/src/cli.mjs

@@ -142,6 +142,7 @@ Working
   task block <id>      Record why a task cannot move
   task unblock <id>    Put a blocked task back where it was
   task reopen <id>     Reopen finished work, with a reason
+  task merge <id>      Fold a duplicate into the task that keeps the work
   derive [feature]     Turn accepted specifications into tasks
 
 Knowledge
@@ -242,6 +243,10 @@ Flags worth knowing
   feature specify --not <text>
                        What the feature deliberately does not do. Repeatable.
                        Its counterpart is --in, and --out stays global
+  ui | start --port <number>
+                       Serve on this port instead of 4317. Every project defaults
+                       to the same port, so the second one to start is refused
+                       and needs this
 
 Exit codes
   0 it worked, 1 something was found or refused, 2 the command was misused`;
@@ -757,6 +762,23 @@ const service = () => import("./service/manage.mjs");
 // later rename of one field cannot silently make `ui` claim nothing is running.
 const isRunning = (report) => report?.state === "running" || report?.running === true;
 
+/**
+ * The port to serve on, when the default one is taken.
+ *
+ * The refusal for a held port told the reader to start on another port and no
+ * command could. This is that flag, validated here rather than in two places:
+ * `ui` and `start` are the same decision made twice, and a port that is not a
+ * usable number has to be refused before a process is spawned against it.
+ */
+function portFrom(ctx) {
+  if (ctx.flags.port === undefined) return null;
+  const value = Number(ctx.flags.port);
+  if (!Number.isInteger(value) || value < 1024 || value > 65535) {
+    throw new UsageError(`--port takes a whole number between 1024 and 65535. ${JSON.stringify(String(ctx.flags.port))} is not one.`);
+  }
+  return value;
+}
+
 async function cmdUi(ctx) {
   const { serviceStatus, startService } = await service();
   const current = await serviceStatus(ctx.root);
@@ -769,21 +791,25 @@ async function cmdUi(ctx) {
       ]),
     };
   }
+  const port = portFrom(ctx);
   if (!ctx.apply) {
     return planned(current, "start the control center",
-      R.wrap("The control center is not running. Starting it opens one local process for this project and listens on the loopback address only."));
+      R.wrap(`The control center is not running. Starting it opens one local process for this project and listens on the loopback address only${port ? `, on port ${port}` : ""}.`));
   }
-  const started = await startService(ctx.root, { actor: ctx.actor });
+  const started = await startService(ctx.root, { actor: ctx.actor, ...(port ? { port } : {}) });
   return { data: { applied: true, service: started }, text: report(ctx, "Control center started", started) };
 }
 
 async function cmdStart(ctx) {
   const { startService, serviceStatus } = await service();
+  const port = portFrom(ctx);
   if (!ctx.apply) {
     return planned(await serviceStatus(ctx.root), "start the local service",
-      "Starting the service opens one local process for this project.");
+      port
+        ? `Starting the service opens one local process for this project, on port ${port}.`
+        : "Starting the service opens one local process for this project.");
   }
-  const started = await startService(ctx.root, { actor: ctx.actor });
+  const started = await startService(ctx.root, { actor: ctx.actor, ...(port ? { port } : {}) });
   return { data: { applied: true, service: started }, text: report(ctx, "Service started", started) };
 }
 
@@ -1213,7 +1239,13 @@ async function cmdTaskUnblock(ctx) {
   }
   const { unblockTask } = await lifecycle();
   const task = await unblockTask(ctx.root, id, { actor: ctx.actor, to, note: ctx.flags.note ?? null });
-  return { data: { applied: true, task }, text: `${task.id} is ${R.status(task.status)} again.` };
+  return {
+    data: { applied: true, task },
+    text: R.stitch([
+      `${task.id} is ${R.status(task.status)} again.`,
+      task.unclaimed ? R.wrap(task.unclaimed) : null,
+    ]),
+  };
 }
 
 /**
@@ -2166,6 +2198,61 @@ async function cmdTaskBlock(ctx) {
   return { data: { applied: true, task }, text: `${task.id} is Blocked. The reason is on the record.` };
 }
 
+/**
+ * Fold a duplicate task into the one that keeps the work.
+ *
+ * There is no delete. A task carries why it existed and what proved it, and
+ * history here is append only, so a deleted task would take its evidence with it
+ * and leave a commit message pointing at an identifier nobody can look up. The
+ * duplicate is superseded and says which task replaced it, which is the same
+ * answer for the reader and a better one for the record.
+ */
+async function cmdTaskMerge(ctx) {
+  const duplicate = requireWord(ctx.words, 2, "Say which task is the duplicate: superdev task merge <duplicate-id> --into <TASK-id>.");
+  const survivor = String(requireFlag(ctx.flags, "into", "Say which task keeps the work: --into <TASK-id>."));
+  const { planMerge, mergeTasks } = await import("./tasks/merge.mjs");
+
+  if (!ctx.apply) {
+    const plan = await planMerge(ctx.root, duplicate, survivor);
+    const rows = Object.entries(plan.moving)
+      .filter(([, n]) => n > 0)
+      .map(([kind, n]) => [MERGE_LABEL[kind] ?? kind, String(n)]);
+    return planned(plan, "merge them", R.stitch([
+      R.wrap(`Would fold ${plan.duplicate.id} ${plan.duplicate.name} into ${plan.survivor.id} ${plan.survivor.name}.`),
+      rows.length ? R.block("What would move", R.table(["What", "How many"], rows)) : R.wrap("Nothing is recorded against it yet, so only its status would change."),
+      plan.releasing ? R.wrap("Its claim would be released rather than moved, because an assignment names who took the work.") : null,
+      plan.staying.history
+        ? R.wrap(`${countWord(plan.staying.history, "activity event")} would stay on ${plan.duplicate.id}, because history records a moment and cannot be moved to another record without saying something untrue about the past.`)
+        : null,
+      R.wrap(`${plan.duplicate.id} would become Superseded and point at ${plan.survivor.id}. Nothing is deleted.`),
+    ]));
+  }
+
+  const out = await mergeTasks(ctx.root, duplicate, survivor, {
+    actor: ctx.actor, reason: ctx.flags.reason ? String(ctx.flags.reason) : null,
+  });
+  const rows = Object.entries(out.moved).filter(([, n]) => n > 0);
+  return {
+    data: out,
+    text: R.stitch([
+      `${out.duplicate.id} is merged into ${out.survivor.id}.`,
+      rows.length
+        ? R.block("Moved", R.table(["What", "How many"], rows.map(([k, n]) => [MERGE_LABEL[k] ?? k, String(n)])))
+        : null,
+      R.wrap(`${out.duplicate.id} is ${R.status(out.duplicate.status)} and points at ${out.survivor.id}, so anyone who finds the old identifier is told where the work went.`),
+    ]),
+  };
+}
+
+const MERGE_LABEL = {
+  evidence: "Evidence",
+  contractLinks: "Contract links (copied, not moved)",
+  dependencies: "Dependencies",
+  memories: "Memory entries",
+  changes: "Recorded changes",
+  children: "Child tasks",
+};
+
 async function cmdTaskReopen(ctx) {
   const id = requireWord(ctx.words, 2, "Say which task to reopen: superdev task reopen <id>.");
   const reason = requireFlag(ctx.flags, "reason", "Reopening finished work needs a reason, because the record already said it was done.");
@@ -2176,7 +2263,15 @@ async function cmdTaskReopen(ctx) {
   }
   const { reopenTask } = await lifecycle();
   const task = await reopenTask(ctx.root, id, { reason, to, actor: ctx.actor });
-  return { data: { applied: true, task }, text: `${task.id} is open again and is ${R.status(task.status)}.` };
+  return {
+    data: { applied: true, task },
+    // A task nobody holds lands Ready, and the reason is said rather than left
+    // for the reader to notice by comparing this against what they expected.
+    text: R.stitch([
+      `${task.id} is open again and is ${R.status(task.status)}.`,
+      task.unclaimed ? R.wrap(task.unclaimed) : null,
+    ]),
+  };
 }
 
 // ---------------------------------------------------------------------- derive
@@ -3069,6 +3164,7 @@ const COMMANDS = {
   "task cancel": cmdTaskCancel,
   "task complete": cmdTaskComplete,
   "task block": cmdTaskBlock,
+  "task merge": cmdTaskMerge,
   "task reopen": cmdTaskReopen,
   "docs generate": cmdDocsGenerate,
   "docs diff": cmdDocsDiff,

package/src/db/migrations/014_task_superseded_by.sql

@@ -0,0 +1,19 @@
+-- Which task replaced this one.
+--
+-- Two records for the same work split its evidence and its progress: each looks
+-- half finished, the feature they serve can never show either as done, and nothing
+-- says they are the same work. Deleting one is not the answer, because a task
+-- carries the reasons it existed and the evidence recorded against it, and history
+-- here is append only by design.
+--
+-- So a duplicate is superseded, and this is where it says by what. Without the
+-- column the relationship could only live in prose in an activity event, which
+-- nothing can follow: somebody who finds the old identifier in a commit message or
+-- a branch name has to be told where the work went.
+--
+-- memory_entries has carried a superseded_by since the first migration for exactly
+-- this reason. Tasks needed the same thing and did not have it.
+
+ALTER TABLE tasks ADD COLUMN superseded_by TEXT REFERENCES tasks(id);
+
+CREATE INDEX tasks_superseded_by ON tasks(superseded_by) WHERE superseded_by IS NOT NULL;

package/src/docs/render.mjs

@@ -22,7 +22,7 @@ import { dirname, join, posix } from "node:path";
 import { query, mutate, create, recordActivity, currentProject, json } from "../db/store.mjs";
 import { assertStorable } from "../model/screening.mjs";
 import { slugify } from "../model/ids.mjs";
-import { EDGE_CASE_CATEGORIES, MODULE_STEPS } from "../model/vocabulary.mjs";
+import { EDGE_CASE_CATEGORIES, MODULE_STEPS, AMBIENT_EVENTS } from "../model/vocabulary.mjs";
 import * as T from "./templates.mjs";
 
 export const MARKER = "superdev:generated";
@@ -145,8 +145,9 @@ async function snapshot(db, projectId) {
     db,
     `SELECT sequence, event_type, summary, actor_label, created_at FROM activity_events
      WHERE project_id = ? AND event_type NOT LIKE 'documentation_%'
+       AND event_type NOT IN (${AMBIENT_EVENTS.map(() => "?").join(", ")})
      ORDER BY sequence DESC LIMIT 200`,
-    projectId,
+    projectId, ...AMBIENT_EVENTS,
   );
 
   index(s);

package/src/docs/templates.mjs

@@ -1173,7 +1173,7 @@ export function changelog(data) {
   return doc(
     REGENERATED,
     `# ${text(data.project.name, "Project")} - Changelog`,
-    "Specification and decision changes, newest first, taken from the append-only activity log. Task and session traffic stays in the control center.",
+    "Specification, decision and task changes, newest first, taken from the append-only activity log. File and session traffic stays in the control center, because a note that files moved is not a change to anything described here.",
     table(
       ["#", "Date", "Change", "Actor"],
       data.entries.map((e) => [e.sequence, e.date, e.summary, e.actor]),

package/src/model/vocabulary.mjs

@@ -13,6 +13,32 @@ export const OPEN_TASK_STATUSES = TASK_STATUSES.filter(
 
 export const TERMINAL_TASK_STATUSES = ["complete", "cancelled", "superseded"];
 
+/**
+ * Events that describe the working tree or a session, rather than a record.
+ *
+ * Generated documents are a projection of the database, so what makes one stale is
+ * a change to a record it renders. A `code_changed` event is a note that files
+ * moved; it changes nothing any document projects. Freshness counted it anyway, so
+ * every commit marked all 303 documents stale, and since the release gate runs
+ * doctor after the commit, the gate could never pass: regenerating cleared it, the
+ * next commit brought it back.
+ *
+ * The changelog had the matching half of the same confusion. It renders every event
+ * that is not a documentation event, while its own description says "Task and
+ * session traffic stays in the control center". The description was right about
+ * what belongs there and the query did not implement it.
+ *
+ * Held here because two modules have to agree about it: the one that decides what a
+ * document renders, and the one that decides when a document is out of date.
+ */
+export const AMBIENT_EVENTS = [
+  "code_changed",
+  "untracked_work",
+  "session_started",
+  "session_ended",
+  "session_compacted",
+];
+
 /** Human-facing label. Title Case, plain language, no internal vocabulary. */
 export const LABEL = {
   draft: "Draft",

package/src/progress/index.mjs

@@ -15,7 +15,7 @@
 // project root, so a caller composes several of these inside one read.
 
 import { json, DbError } from "../db/store.mjs";
-import { agrees, count } from "../model/vocabulary.mjs";
+import { agrees, count, AMBIENT_EVENTS } from "../model/vocabulary.mjs";
 
 const DAY_MS = 86_400_000;
 
@@ -715,12 +715,20 @@ export async function freshness(db, projectId) {
   // it rendered at and only then records its own documentation_generated event,
   // so comparing against the raw maximum sequence would report every document as
   // stale the instant it was produced, and no run could ever clear it.
+  // Documentation events are excluded because a render is not a content change,
+  // and ambient events because a note that files moved or a session started
+  // changes no record any document projects. Counting those made every commit
+  // mark all of them stale, which the release gate then refused, and regenerating
+  // only cleared it until the next commit.
+  const IGNORED = [
+    "documentation_generated", "documentation_proposal_raised",
+    "documentation_proposal_resolved", "documentation_possibly_stale",
+    ...AMBIENT_EVENTS,
+  ];
   const contentRevision = (await db.get(
     `SELECT max(sequence) AS s FROM activity_events
-      WHERE project_id = ? AND event_type NOT IN
-            ('documentation_generated','documentation_proposal_raised',
-             'documentation_proposal_resolved','documentation_possibly_stale')`,
-    projectId,
+      WHERE project_id = ? AND event_type NOT IN (${IGNORED.map(() => "?").join(", ")})`,
+    projectId, ...IGNORED,
   ))?.s ?? 0;
   const live = documents.filter((d) => d.sync_status !== "retired");
   const behind = live.filter((d) => (d.database_revision ?? 0) < contentRevision);

package/src/runtime/hooks.mjs

@@ -22,7 +22,7 @@
 // Secrets never reach the output: everything user facing goes through
 // sanitizeExternal, which strips secret-shaped values and home paths.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, writeSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, writeSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { paths, query } from "../db/store.mjs";
 import { availableMigrations } from "../db/migrate.mjs";
@@ -472,11 +472,28 @@ async function postToolUse(root, payload) {
   if (!MUTATING_TOOLS.has(tool) && !viaShell) return EMPTY;
 
   let file = payload?.tool_input?.file_path ?? payload?.tool_input?.notebook_path ?? payload?.tool_input?.path;
+  // Whether anything is newly changed, decided before the paths are marked.
+  //
+  // git reports a file as changed until it is committed, so a shell command run
+  // after a task is completed re-reported the very files that task had produced,
+  // and the readiness report raised its only high-severity warning about work
+  // that had just been finished, evidenced and recorded. Any redirect or heredoc
+  // is enough to make the hook look, so this happened on the first command after
+  // every completion.
+  //
+  // The paths already seen are the answer. Work noticed twice is one piece of
+  // work; a path not seen before is a genuine change. Computed here because
+  // markTouched below would otherwise record these paths and make every one of
+  // them look familiar.
+  let fresh = true;
   if (viaShell) {
     const changed = await changedFiles(root);
     // A command that looked like a write and changed nothing is not work.
     if (!changed.length) return EMPTY;
+    const moved = movedSince(root, changed, readTouched(root).attributed);
+    fresh = moved.length > 0;
     markTouched(root, changed);
+    attribute(root, moved);
     file = file ?? changed[0];
   }
   markTouched(root, [file]);
@@ -487,7 +504,7 @@ async function postToolUse(root, payload) {
   // files touched by the active task; when there is no active task, that
   // absence is the fact worth keeping. Rate limited so a long editing run
   // leaves one honest marker rather than one per keystroke.
-  await noteUntrackedWork(root, file).catch(() => {});
+  if (fresh) await noteUntrackedWork(root, file).catch(() => {});
   await markDocsPossiblyStale(root, file).catch(() => {});
   return EMPTY;
 }
@@ -521,9 +538,12 @@ function readTouched(root) {
       total: Number.isFinite(parsed.total) ? parsed.total : 0,
       since: typeof parsed.since === "string" ? parsed.since : null,
       lastEventAt: typeof parsed.lastEventAt === "string" ? parsed.lastEventAt : null,
+      // When each path was last accounted for, which `paths` cannot answer
+      // because a flush empties it.
+      attributed: parsed.attributed && typeof parsed.attributed === "object" ? parsed.attributed : {},
     };
   } catch {
-    return { paths: [], total: 0, since: null, lastEventAt: null };
+    return { paths: [], total: 0, since: null, lastEventAt: null, attributed: {} };
   }
 }
 
@@ -537,6 +557,61 @@ function writeTouched(root, state) {
   }
 }
 
+/**
+ * Whether a path is the product, rather than Superdev's own bookkeeping about it.
+ *
+ * markTouched has always skipped `.superdev/`, and the freshness comparison did
+ * not, so the runtime directory was picking up modification stamps. One of those
+ * files is the database write-ahead log, which moves on every single command, so
+ * every command would have looked like new work and the comparison would have
+ * decided nothing. Both callers now ask the same question in the same place.
+ */
+const isProjectWork = (rel) => Boolean(rel) && !rel.startsWith(".superdev/");
+
+/**
+ * Which of these paths have actually moved since they were last accounted for.
+ *
+ * git reports a file as changed until it is committed, so every shell command run
+ * between an edit and its commit re-reports the same files. That made the hook
+ * record fresh untracked work for edits a completed task had already produced and
+ * evidenced, and the readiness report then raised its only high-severity warning
+ * about work that was finished. Any redirect or heredoc is enough to make the hook
+ * look, so it happened on the first command after every completion.
+ *
+ * The pending path list cannot answer this, because a flush empties it. A
+ * modification time can: a path re-reported without moving is the same work seen
+ * again, and a path whose file has changed since is new work whoever is holding
+ * the task. Missing stats count as moved, because failing to notice real work is
+ * the worse mistake of the two.
+ */
+export function movedSince(root, candidates, attributed) {
+  candidates = candidates.filter(isProjectWork);
+  const moved = [];
+  for (const path of candidates) {
+    let stamp = null;
+    try {
+      stamp = statSync(join(root, path)).mtimeMs;
+    } catch {
+      // Deleted, or unreadable. Either way it is not the file we accounted for.
+      moved.push([path, Date.now()]);
+      continue;
+    }
+    if (stamp > (Number(attributed[path]) || 0)) moved.push([path, stamp]);
+  }
+  return moved;
+}
+
+/** Record that these paths are accounted for, at the state they are in now. */
+function attribute(root, moved) {
+  if (!moved.length) return;
+  const state = readTouched(root);
+  const next = { ...state.attributed };
+  for (const [path, stamp] of moved) next[path] = stamp;
+  // Bounded, oldest first, so a long-lived project does not grow this forever.
+  const entries = Object.entries(next).sort((a, b) => b[1] - a[1]).slice(0, MAX_TOUCHED);
+  writeTouched(root, { ...state, attributed: Object.fromEntries(entries) });
+}
+
 /**
  * Record which project-relative paths changed.
  *
@@ -550,7 +625,7 @@ export function markTouched(root, files) {
     if (!file) continue;
     const rel = relative(root, canonical(root, file)).split(sep).join("/");
     if (!rel || rel.startsWith("../") || isAbsolute(rel)) continue;
-    if (rel.startsWith(".superdev/")) continue; // Superdev's own runtime state is not project work.
+    if (!isProjectWork(rel)) continue;
     kept.push(rel);
   }
   if (!kept.length) return null;
@@ -562,6 +637,7 @@ export function markTouched(root, files) {
     total: state.total + kept.length,
     since: state.since ?? new Date().toISOString(),
     lastEventAt: state.lastEventAt,
+    attributed: state.attributed,
   };
   writeTouched(root, next);
   return next;
@@ -633,7 +709,10 @@ export async function flushTouched(root, { force = false } = {}) {
     metadata: { files: state.paths.length, changes: state.total },
   }).catch((err) => ({ recorded: false, reason: message(err) }));
 
-  writeTouched(root, { paths: [], total: 0, since: null, lastEventAt: new Date().toISOString() });
+  writeTouched(root, {
+    paths: [], total: 0, since: null, lastEventAt: new Date().toISOString(),
+    attributed: state.attributed,
+  });
   return result;
 }
 

package/src/service/manage.mjs

@@ -135,6 +135,19 @@ export function probeHealth(host, port, timeout = PROBE_TIMEOUT_MS) {
   });
 }
 
+/**
+ * A path a reader can retype, shortened at home so a long absolute path does not
+ * bury the part that identifies the project.
+ *
+ * Every message about a port used to describe it without saying whose it was,
+ * even though the health probe had already been handed the answer, so finding out
+ * meant opening candidate directories one at a time.
+ */
+export function displayRoot(path) {
+  const home = homedir();
+  return home && path.startsWith(`${home}/`) ? `~/${path.slice(home.length + 1)}` : path;
+}
+
 /**
  * What is actually true for this project right now. Distinguishes a service we
  * manage from a stale lock, from a start in progress, from someone else holding
@@ -160,14 +173,31 @@ export async function inspect(root, { port = null, host = DEFAULTS.host } = {})
       };
     }
     if (health) {
+      // Not running, and the default port happens to be busy. Those are two
+      // separate facts and only the first one is about this project.
+      //
+      // This used to report `foreign`, which made both commands lie. `start`
+      // never blocked on it: the server scans forward from the requested port on
+      // EADDRINUSE, so a second project quietly lands on the next free one, and
+      // the message told the reader to do something the tool was already doing.
+      // `stop` did worse. On a project with nothing running it refused, and told
+      // the reader to go and stop a different project, which they have no reason
+      // to touch.
+      //
+      // Reserving `foreign` for the case that is genuinely somebody else's
+      // service in our place is what makes the word mean something.
       return {
-        state: "foreign",
+        state: "stopped",
         managed: false,
         lock: null,
         health,
-        port: candidate,
+        port: null,
         host,
-        explanation: `Port ${candidate} is held by a Superdev service for a different project. Start this one on another port.`,
+        portInUse: candidate,
+        heldBy: health.projectRoot ?? null,
+        explanation: `Nothing is running for this project. Port ${candidate} is held by ${
+          health.projectRoot ? `the Superdev service for ${displayRoot(health.projectRoot)}` : "another Superdev service"
+        }, so starting this one will use the next free port instead. Pass --port <number> to choose.`,
       };
     }
     return {
@@ -217,7 +247,9 @@ export async function inspect(root, { port = null, host = DEFAULTS.host } = {})
       health,
       port: lock.port,
       host: lock.host ?? host,
-      explanation: `Port ${lock.port} is answering, but it is not the service this lock file describes. Something else took the port.`,
+      explanation: `Port ${lock.port} is answering, but it is not the service this lock file describes${
+        health.projectRoot ? `: it belongs to ${displayRoot(health.projectRoot)}` : ""
+      }. This project's service is gone and something else took its port. Run \`superdev start --apply\` to bring this one back on a free port.`,
     };
   }
   return {
@@ -335,7 +367,12 @@ export async function startService(root, options = {}) {
   );
   if (!held) {
     if (view.state === "foreign") {
-      throw new ServiceError(E.FOREIGN, view.explanation, { port: view.port });
+      throw new ServiceError(E.FOREIGN, view.explanation, {
+        port: view.port,
+        // The caller cannot act on a refusal whose subject it cannot see, and the
+        // probe already knows it. `superdev services` prints it; a script reads it.
+        heldBy: view.health?.projectRoot ?? null,
+      });
     }
     return { ...summarize(root, view), alreadyRunning: true };
   }

package/src/tasks/lifecycle.mjs

@@ -295,19 +295,10 @@ export async function claimTask(root, taskId, who = {}) {
   // out to git, and subprocess work inside a write transaction holds the
   // exclusive lock across it.
   if (!developerId && !agentId) {
-    try {
-      const { resolveIdentity, detectHarness } = await import("../runtime/identity.mjs");
-      const identity = await resolveIdentity(root, {
-        harness: detectHarness(process.env).harness,
-        displayName: who.displayName ?? (actor !== "superdev" ? actor : undefined),
-      });
-      developerId = developerId ?? identity.developer?.id ?? null;
-      agentId = agentId ?? identity.agent?.id ?? null;
-      branchId = branchId ?? identity.branch?.id ?? null;
-    } catch {
-      // An unresolvable identity must not block the claim: the task still gets
-      // held, and the assignment simply says so rather than naming someone.
-    }
+    const identity = await whoIsActing(root, { actor, displayName: who.displayName });
+    developerId = developerId ?? identity.developerId;
+    agentId = agentId ?? identity.agentId;
+    branchId = branchId ?? identity.branchId;
   }
 
   return mutate(root, async (db) => {
@@ -361,21 +352,11 @@ export async function claimTask(root, taskId, who = {}) {
 
     // A lease is a statement to somebody else. With no peer configured there is
     // nobody to hear it, and the local unique index is already the whole answer.
-    const peer = await db.get("SELECT alias FROM sync_peers WHERE status = 'connected' LIMIT 1")
-      .catch(() => null);
     try {
-      await create(db, "task_assignment", {
-        task_id: taskId,
-        developer_id: developerId,
-        agent_id: agentId,
-        branch_id: branchId,
-        session_id: sessionId,
-        assigned_at: nowIso(),
-        active: 1,
-        lease_holder: peer?.alias ?? null,
-        lease_expires_at: peer ? leaseExpiry(nowIso()) : null,
-      }, { projectId: task.project_id, actor, sessionId, taskId, activityType: "task_claimed",
-           activitySummary: `${taskId} claimed.` });
+      await assign(db, task, {
+        developerId, agentId, branchId, sessionId, actor,
+        summary: `${taskId} claimed.`,
+      });
     } catch (err) {
       // Only a uniqueness failure means someone else got the claim first. The
       // test used to accept any message containing "constraint", so a foreign
@@ -403,8 +384,6 @@ export async function claimTask(root, taskId, who = {}) {
     //
     // Written here rather than in each caller, because the control centre claims
     // tasks too and the field has to mean the same thing whichever surface moved it.
-    await pointSessionAt(db, task.project_id, sessionId, taskId);
-
     return db.get("SELECT * FROM tasks WHERE id = ?", taskId);
   });
 }
@@ -489,6 +468,7 @@ export async function blockTask(root, taskId, { reason, actor = "superdev", sess
 
 /** Return to whatever the task was doing before it blocked, not to a guess. */
 export async function unblockTask(root, taskId, { actor = "superdev", note = null, to = null } = {}) {
+  const identity = await whoIsActing(root, { actor });
   return mutate(root, async (db) => {
     const task = await taskOr404(db, taskId);
     if (task.status !== "blocked") {
@@ -500,8 +480,10 @@ export async function unblockTask(root, taskId, { actor = "superdev", note = nul
         ORDER BY sequence DESC LIMIT 1`,
       taskId,
     );
-    const target = to ?? (["in_progress", "in_review", "verifying"].includes(previous?.from_status) ? previous.from_status : "ready");
-    return move(db, task, target, { actor, note, activityType: "task_unblocked" });
+    const wanted = to ?? (ACTIVE.has(previous?.from_status) ? previous.from_status : "ready");
+    const owned = await ownedTarget(db, task, wanted, { actor, identity });
+    const moved = await move(db, task, owned.target, { actor, note, activityType: "task_unblocked" });
+    return owned.note ? { ...moved, unclaimed: owned.note } : moved;
   });
 }
 
@@ -691,20 +673,125 @@ export async function completeTask(root, taskId, { actor = "superdev", sessionId
 }
 
 /** Reopening is a recorded decision, never a quiet edit of a finished record. */
+/**
+ * Who is acting, resolved outside every transaction.
+ *
+ * resolveIdentity shells out to git, and subprocess work inside a write
+ * transaction holds the engine's exclusive lock across it, so this always runs
+ * before mutate opens. A claim recording three nulls says nothing about who holds
+ * the task, which is the only reason the claim exists.
+ */
+async function whoIsActing(root, { actor, displayName } = {}) {
+  try {
+    const { resolveIdentity, detectHarness } = await import("../runtime/identity.mjs");
+    const identity = await resolveIdentity(root, {
+      harness: detectHarness(process.env).harness,
+      displayName: displayName ?? (actor && actor !== "superdev" ? actor : undefined),
+    });
+    return {
+      developerId: identity.developer?.id ?? null,
+      agentId: identity.agent?.id ?? null,
+      branchId: identity.branch?.id ?? null,
+    };
+  } catch {
+    // An unresolvable identity must not block the work: the claim still happens
+    // and simply says so rather than naming somebody.
+    return { developerId: null, agentId: null, branchId: null };
+  }
+}
+
+/**
+ * Create the claim, point the session at it, and say who holds it now.
+ *
+ * Factored out of claimTask so that reopening a task can take the claim through
+ * exactly the same path. Two ways of claiming would be two things to keep in
+ * agreement, and the last three defects in this area were all one fact recorded
+ * in one place and read from another.
+ */
+async function assign(db, task, { developerId, agentId, branchId, sessionId, actor, summary }) {
+  const peer = await db.get("SELECT alias FROM sync_peers WHERE status = 'connected' LIMIT 1")
+    .catch(() => null);
+  await create(db, "task_assignment", {
+    task_id: task.id,
+    developer_id: developerId,
+    agent_id: agentId,
+    branch_id: branchId,
+    session_id: sessionId,
+    assigned_at: nowIso(),
+    active: 1,
+    lease_holder: peer?.alias ?? null,
+    lease_expires_at: peer ? leaseExpiry(nowIso()) : null,
+  }, { projectId: task.project_id, actor, sessionId, taskId: task.id, activityType: "task_claimed",
+       activitySummary: summary });
+  await pointSessionAt(db, task.project_id, sessionId, task.id);
+}
+
+/**
+ * Statuses that assert somebody is working on the task right now.
+ *
+ * A task in one of these with no claim behind it is a state the record should not
+ * be able to reach, and it had two ways in. `task reopen` moved a completed task
+ * straight to in_progress, and `task unblock` restored whatever status the task
+ * held before it was blocked. Neither took a claim, so the session's active task
+ * stayed null while a task said it was in progress, and the untracked-work hook,
+ * which reads exactly that field, then recorded every later edit as work nobody
+ * had accounted for. Readiness reported it at high severity against work being
+ * done on a correctly specified, in-progress task.
+ */
+const ACTIVE = new Set(["in_progress", "in_review", "verifying"]);
+
+/**
+ * The status a transition may actually use, given who holds the task.
+ *
+ * An unclaimed task drops to ready rather than being claimed on somebody's
+ * behalf: reopening a task is a statement that the work is not finished, which is
+ * a different fact from somebody working on it this minute, and taking a claim
+ * silently would be worse than asking for one. A task the caller already holds
+ * keeps the active status, and the session is pointed at it either way.
+ */
+async function ownedTarget(db, task, target, { actor, identity }) {
+  if (!ACTIVE.has(target)) return { target, note: null };
+  const held = await activeAssignment(db, task.id);
+  if (held) {
+    // Somebody already holds it, including possibly another machine. Their claim
+    // stands; this only makes sure the session it belongs to points at it.
+    await pointSessionAt(db, task.project_id, held.session_id, task.id);
+    return { target, note: null };
+  }
+  // Nobody holds it. Dropping to ready is not available: the status machine only
+  // allows complete to in_progress, and loosening a transition to work around a
+  // missing claim would be the wrong repair. So the claim is taken, by the actor
+  // who asked for this, which is an explicit act that already carries a reason.
+  await assign(db, task, {
+    developerId: identity?.developerId ?? null,
+    agentId: identity?.agentId ?? null,
+    branchId: identity?.branchId ?? null,
+    sessionId: null,
+    actor,
+    summary: `${task.id} claimed by reopening it.`,
+  });
+  return { target, note: `It is claimed for ${actor}, because a task in progress that no session owns is a state the record should not be able to reach.` };
+}
+
 export async function reopenTask(root, taskId, { reason, actor = "superdev", to = null } = {}) {
   if (!reason) throw new TaskError(E.REASON_REQUIRED, "Reopening a finished task needs a reason, because the record already said it was done.");
+  // Before mutate, because reopening may have to take the claim and resolving who
+  // is acting shells out to git.
+  const identity = await whoIsActing(root, { actor });
   return mutate(root, async (db) => {
     const task = await taskOr404(db, taskId);
     if (OPEN(task.status)) {
       throw new TaskError(E.INVALID_TRANSITION, `${taskId} is ${task.status} and already open. There is nothing to reopen.`);
     }
-    const target = to ?? (task.status === "complete" ? "in_progress" : "ready");
+    const wanted = to ?? (task.status === "complete" ? "in_progress" : "ready");
+    const { target, note } = await ownedTarget(db, task, wanted, { actor, identity });
     const cleared = await patch(db, "task", taskId, task.version, {
       completed_at: null,
       cancelled_at: null,
     }, { projectId: task.project_id, actor, activityType: "task_reopened",
          activitySummary: `${taskId} reopened: ${reason}` });
-    return move(db, cleared, target, { actor, note: reason, activityType: "task_reopened" });
+    const moved = await move(db, cleared, target, { actor, note: reason, activityType: "task_reopened" });
+    return note ? { ...moved, unclaimed: note } : moved;
   });
 }
 

package/src/tasks/merge.mjs

@@ -0,0 +1,250 @@
+// Folding a duplicate task into the one that keeps the work.
+//
+// Deriving twice, or creating by hand what derivation had already created, leaves
+// two records for one piece of work. Each collects some of the evidence, so each
+// looks half finished, the feature they serve can never show either as done, and
+// progress counts the same work twice while completing neither.
+//
+// Deleting one is the obvious move and the wrong one. A task carries why it
+// existed, what it implements and what proved it, and history here is append only
+// on purpose: a deleted task takes its evidence with it and leaves a commit
+// message or a branch name pointing at an identifier nobody can look up. So
+// nothing is deleted. What the duplicate owns moves to the survivor, the duplicate
+// becomes superseded, and it says which task replaced it.
+//
+// What does not move, and why:
+//
+//   Activity events stay where they happened. They are a record of a moment, and
+//   rewriting them to point elsewhere would make the log say something that is not
+//   true about the past.
+//
+//   Claims stay with whoever made them. An assignment names a person, a machine
+//   and a branch; moving it would put somebody's name against work they did not
+//   take. The duplicate's claim is released instead.
+
+import { mutate, query, recordActivity, setStatus } from "../db/store.mjs";
+
+export const E = {
+  NOT_FOUND: "E_NOT_FOUND",
+  SAME_TASK: "E_SAME_TASK",
+  DIFFERENT_PROJECT: "E_DIFFERENT_PROJECT",
+  NOT_MERGEABLE: "E_NOT_MERGEABLE",
+  HELD: "E_ALREADY_CLAIMED",
+};
+
+export class MergeError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "MergeError";
+    this.code = code;
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
+/** A task in one of these has already been closed out; merging it again says nothing. */
+const CLOSED = new Set(["superseded", "cancelled"]);
+
+/**
+ * What a merge would move, without moving any of it.
+ *
+ * Counted per kind rather than totalled, because "6 things would move" tells a
+ * reader nothing about whether they meant to move them.
+ */
+export async function planMerge(root, duplicateId, survivorId) {
+  return query(root, async (db) => {
+    const [duplicate, survivor] = await Promise.all([
+      db.get("SELECT * FROM tasks WHERE id = ?", duplicateId),
+      db.get("SELECT * FROM tasks WHERE id = ?", survivorId),
+    ]);
+    refuseImpossible(duplicate, survivor, duplicateId, survivorId);
+
+    const held = await db.get(
+      "SELECT id, developer_id, agent_id FROM task_assignments WHERE task_id = ? AND active = 1",
+      duplicateId,
+    );
+
+    return {
+      duplicate: summary(duplicate),
+      survivor: summary(survivor),
+      moving: {
+        evidence: await countOf(db, "SELECT COUNT(*) AS n FROM verification_evidence WHERE task_id = ?", duplicateId),
+        // Counted as what the survivor would gain, not as what the duplicate has:
+        // a link the survivor already carries is not moved anywhere.
+        contractLinks: await countOf(db,
+          `SELECT COUNT(*) AS n FROM task_contract_links d
+            WHERE d.task_id = ?
+              AND NOT EXISTS (SELECT 1 FROM task_contract_links s
+                               WHERE s.task_id = ? AND s.target_type = d.target_type
+                                 AND s.target_id = d.target_id AND s.relationship = d.relationship)`,
+          duplicateId, survivorId),
+        dependencies: await countOf(db,
+          "SELECT COUNT(*) AS n FROM task_dependencies WHERE task_id = ? OR depends_on_task_id = ?", duplicateId, duplicateId),
+        memories: await countOf(db, "SELECT COUNT(*) AS n FROM memory_entries WHERE task_id = ?", duplicateId),
+        changes: await countOf(db, "SELECT COUNT(*) AS n FROM changes WHERE task_id = ?", duplicateId),
+        children: await countOf(db, "SELECT COUNT(*) AS n FROM tasks WHERE parent_task_id = ?", duplicateId),
+      },
+      // A claim is released rather than moved, and the reader is told so before it
+      // happens rather than discovering it afterwards.
+      releasing: held ? held.id : null,
+      staying: {
+        history: await countOf(db, "SELECT COUNT(*) AS n FROM activity_events WHERE task_id = ?", duplicateId),
+      },
+    };
+  });
+}
+
+/**
+ * Move everything the duplicate owns onto the survivor and supersede it.
+ *
+ * Every move is `OR IGNORE` or guarded, because the survivor may already carry the
+ * same link, and a merge that fails halfway through on a uniqueness constraint
+ * would leave the work split across two tasks with no way to tell which half went
+ * where. The whole thing is one transaction, so it either happens or it does not.
+ */
+export async function mergeTasks(root, duplicateId, survivorId, { actor = "superdev", reason = null } = {}) {
+  return mutate(root, async (db) => {
+    const [duplicate, survivor] = await Promise.all([
+      db.get("SELECT * FROM tasks WHERE id = ?", duplicateId),
+      db.get("SELECT * FROM tasks WHERE id = ?", survivorId),
+    ]);
+    refuseImpossible(duplicate, survivor, duplicateId, survivorId);
+
+    const moved = {};
+
+    moved.evidence = await moveRows(db,
+      "UPDATE verification_evidence SET task_id = ? WHERE task_id = ?", survivorId, duplicateId);
+
+    // Contract links are copied, not moved.
+    //
+    // Moving them emptied the duplicate, and a trigger refuses any task leaving
+    // draft without at least one contract link, so superseding it then failed and
+    // the whole merge rolled back. The trigger is right: a task in an active status
+    // that implements nothing is not a task. Copying is also the truer record,
+    // because the duplicate really was written to implement that criterion, and it
+    // is superseded rather than open so it no longer competes for the work.
+    moved.contractLinks = await moveRows(db,
+      `INSERT OR IGNORE INTO task_contract_links (task_id, target_type, target_id, relationship)
+         SELECT ?, target_type, target_id, relationship FROM task_contract_links WHERE task_id = ?`,
+      survivorId, duplicateId);
+
+    moved.dependencies = await moveRows(db,
+      "UPDATE OR IGNORE task_dependencies SET task_id = ? WHERE task_id = ?", survivorId, duplicateId);
+    moved.dependencies += await moveRows(db,
+      "UPDATE OR IGNORE task_dependencies SET depends_on_task_id = ? WHERE depends_on_task_id = ?", survivorId, duplicateId);
+    // Anything left pointed at the duplicate, and a task cannot depend on itself.
+    await db.run("DELETE FROM task_dependencies WHERE task_id = ? OR depends_on_task_id = ?", duplicateId, duplicateId);
+    await db.run("DELETE FROM task_dependencies WHERE task_id = depends_on_task_id");
+
+    moved.memories = await moveRows(db,
+      "UPDATE memory_entries SET task_id = ? WHERE task_id = ?", survivorId, duplicateId);
+    moved.changes = await moveRows(db,
+      "UPDATE changes SET task_id = ? WHERE task_id = ?", survivorId, duplicateId);
+    moved.children = await moveRows(db,
+      "UPDATE tasks SET parent_task_id = ? WHERE parent_task_id = ?", survivorId, duplicateId);
+
+    // The claim is released, not moved: an assignment names a person, a machine and
+    // a branch, and moving it would put somebody's name against work they did not
+    // take.
+    const held = await db.get(
+      "SELECT id FROM task_assignments WHERE task_id = ? AND active = 1", duplicateId);
+    if (held) {
+      await db.run("UPDATE task_assignments SET active = 0, released_at = ? WHERE id = ?",
+        new Date().toISOString(), held.id);
+    }
+    await db.run(
+      "UPDATE work_sessions SET active_task_id = NULL WHERE project_id = ? AND active_task_id = ?",
+      duplicate.project_id, duplicateId);
+
+    // The pointer is written before the status moves, so nothing can observe a
+    // superseded task that does not say what replaced it.
+    await db.run("UPDATE tasks SET superseded_by = ? WHERE id = ?", survivorId, duplicateId);
+
+    const why = reason
+      ? `${duplicateId} merged into ${survivorId}: ${reason}`
+      : `${duplicateId} merged into ${survivorId} as a duplicate.`;
+    await setStatus(db, "task", duplicateId, "superseded", {
+      projectId: duplicate.project_id,
+      actor,
+      note: why,
+      activityType: "task_updated",
+      activitySummary: why,
+    });
+
+    await recordActivity(db, survivor.project_id, {
+      type: "task_updated",
+      actor,
+      taskId: survivorId,
+      featureId: survivor.feature_id,
+      summary: `${survivorId} absorbed ${duplicateId}: ${describe(moved)}`,
+      metadata: { mergedFrom: duplicateId, moved },
+    });
+
+    return {
+      duplicate: summary(await db.get("SELECT * FROM tasks WHERE id = ?", duplicateId)),
+      survivor: summary(await db.get("SELECT * FROM tasks WHERE id = ?", survivorId)),
+      moved,
+      released: held?.id ?? null,
+    };
+  });
+}
+
+// ------------------------------------------------------------------ helpers
+
+/** Everything that makes a merge impossible, refused in one place. */
+function refuseImpossible(duplicate, survivor, duplicateId, survivorId) {
+  if (duplicateId === survivorId) {
+    throw new MergeError(E.SAME_TASK, `${duplicateId} cannot be merged into itself.`);
+  }
+  if (!duplicate) throw new MergeError(E.NOT_FOUND, `There is no task ${duplicateId}.`);
+  if (!survivor) throw new MergeError(E.NOT_FOUND, `There is no task ${survivorId}.`);
+  if (duplicate.project_id !== survivor.project_id) {
+    throw new MergeError(E.DIFFERENT_PROJECT,
+      `${duplicateId} and ${survivorId} belong to different projects, so merging them would move work between records that do not share a scope.`);
+  }
+  if (duplicate.superseded_by) {
+    throw new MergeError(E.NOT_MERGEABLE,
+      `${duplicateId} was already merged into ${duplicate.superseded_by}. Merge that one instead.`);
+  }
+  if (CLOSED.has(duplicate.status)) {
+    throw new MergeError(E.NOT_MERGEABLE,
+      `${duplicateId} is ${duplicate.status}, so it has already been closed out and there is nothing to fold in.`);
+  }
+  if (CLOSED.has(survivor.status)) {
+    throw new MergeError(E.NOT_MERGEABLE,
+      `${survivorId} is ${survivor.status}, so merging into it would move the work onto a task nobody is going to finish.`);
+  }
+}
+
+const summary = (task) => task && ({
+  id: task.id,
+  name: task.name,
+  status: task.status,
+  featureId: task.feature_id,
+  supersededBy: task.superseded_by ?? null,
+});
+
+async function countOf(db, sql, ...args) {
+  return Number((await db.get(sql, ...args))?.n ?? 0);
+}
+
+/** How many rows a statement actually moved, whichever field the driver reports it in. */
+async function moveRows(db, sql, ...args) {
+  const result = await db.run(sql, ...args);
+  return Number(result?.changes ?? result?.rowsAffected ?? 0);
+}
+
+const describe = (moved) => {
+  const said = Object.entries(moved)
+    .filter(([, n]) => n > 0)
+    .map(([kind, n]) => `${n} ${LABEL[kind] ?? kind}`);
+  return said.length ? said.join(", ") : "nothing to move";
+};
+
+const LABEL = {
+  evidence: "pieces of evidence",
+  contractLinks: "contract links copied across",
+  dependencies: "dependencies",
+  memories: "memory entries",
+  changes: "recorded changes",
+  children: "child tasks",
+};

package/src/verify/index.mjs

@@ -17,6 +17,8 @@
 // saying plainly that a check is manual.
 
 import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 
 import { mutate, query } from "../db/store.mjs";
@@ -50,8 +52,86 @@ const run = promisify(execFile);
  * should be run by a person who has read it.
  */
 
-/** Scripts of this project that may be run, and nothing else. */
-const SCRIPT = /^(src\/cli\.mjs|scripts\/[A-Za-z0-9_\/-]+\.mjs)$/;
+/**
+ * A script inside the project may be run. Whether it is inside is a containment
+ * question, not a question about its path's shape.
+ *
+ * This was `/^(src\/cli\.mjs|scripts\/[A-Za-z0-9_\/-]+\.mjs)$/`, which is
+ * Superdev's own entry point and Superdev's own script directory, hardcoded. Every
+ * other repository layout was refused however plainly the script sat inside the
+ * project: a workspace package, `tools/`, `bin/`, `lib/`, `apps/web/lib/`. The
+ * refusal even said "node may only run this project's own scripts", and the
+ * allowlist did not describe this project. It described Superdev.
+ *
+ * That mattered more than a wrong message. The recorded command is the whole
+ * mechanism by which evidence stops being a one-time opinion, so on any project
+ * whose scripts are not at `scripts/*.mjs` the mechanism quietly did nothing, and
+ * a reader was pushed into moving their files to suit the tool.
+ *
+ * The real risk was never the path's shape. It is a node option before the script
+ * path, which can load arbitrary code, and that rule is enforced separately and
+ * unchanged. What containment has to add is that the script is under the project
+ * root once symlinks are resolved, so a link pointing out of the tree is refused
+ * even though its path looks local.
+ */
+const SCRIPT_EXTENSION = /\.(mjs|cjs|js)$/;
+
+function outsideProject(root, script) {
+  // A flag in the script position is the actual risk, and it is refused on shape
+  // rather than on containment: `--require=./evil.js` ends in `.js` and names no
+  // script at all. Checking the extension first let exactly that through.
+  if (script.startsWith("-")) {
+    return "node may not be given an option before the script path, because an option can load arbitrary code";
+  }
+  if (!SCRIPT_EXTENSION.test(script)) return `not a script: ${script}`;
+  if (isAbsolute(script)) return `an absolute path names a place rather than something in this project: ${script}`;
+  if (!root) {
+    return `the project root is not known here, so whether ${script} is inside it cannot be decided`;
+  }
+  const base = realpathOrSelf(resolve(root));
+  const target = resolvedWithin(base, script);
+  if (target !== base && !target.startsWith(base + sep)) {
+    return `node may only run scripts inside this project, and ${script} resolves outside it`;
+  }
+  return null;
+}
+
+/**
+ * The script's real location, resolving every symlink on the way to it.
+ *
+ * realpath on the whole path answers nothing when the file does not exist yet, and
+ * falling back to the unresolved path let a directory symlink out of the tree
+ * pass: `escape/hosts.mjs`, where `escape` links to somewhere else, resolves under
+ * the root only because the leaf could not be resolved. So the deepest ancestor
+ * that does exist is resolved instead, and the rest is appended to it.
+ */
+function resolvedWithin(base, script) {
+  const full = resolve(base, script);
+  let head = full;
+  const tail = [];
+  for (;;) {
+    const real = realpathSafe(head);
+    if (real) return tail.length ? resolve(real, ...tail.reverse()) : real;
+    const parent = dirname(head);
+    // Reached the filesystem root without finding anything that exists.
+    if (parent === head) return full;
+    tail.push(basename(head));
+    head = parent;
+  }
+}
+
+const realpathSafe = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return null;
+  }
+};
+
+/** Symlinks resolved where possible, so a link out of the tree cannot hide. */
+function realpathOrSelf(path) {
+  return realpathSafe(path) ?? path;
+}
 
 /**
  * Flags each program may carry.
@@ -71,7 +151,7 @@ const CHANGES_STATE = /^--(apply|force|write|fix|delete|remove)\b/;
 export const E = { UNSAFE: "E_UNSAFE_CHECK" };
 
 /** Why a command will not be run here, or null when it will. */
-export function refuseReason(command) {
+export function refuseReason(command, root = null) {
   const text = String(command ?? "").trim();
   if (!text) return "no command recorded";
   // Shell punctuation cannot do anything through execFile, but its presence
@@ -96,7 +176,8 @@ export function refuseReason(command) {
     // arbitrary code, which is the whole risk with running node at all.
     const [script, ...args] = rest;
     if (!script) return "node with no script";
-    if (!SCRIPT.test(script)) return `node may only run this project's own scripts, not ${script}`;
+    const outside = outsideProject(root, script);
+    if (outside) return outside;
     for (const a of args) {
       if (CHANGES_STATE.test(a)) return "it would change something, and a check must not";
     }
@@ -152,7 +233,7 @@ export function tokenize(command) {
  * validator which starts finding things is how a claim stops being true.
  */
 export async function runCheck(root, command, { timeoutMs = 120000 } = {}) {
-  const refused = refuseReason(command);
+  const refused = refuseReason(command, root);
   if (refused) return { result: "error", detail: refused };
 
   const [bin, ...rest] = tokenize(command);