@ran-sh/dsh-crew 1.10.3 → 1.10.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.10.3",
+  "version": "1.10.5",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/docs/installation.md

@@ -56,6 +56,33 @@ reserves handoff ownership before releasing its update lock, resumes any
 unfinished handoff first, and succeeds only after the isolated 3210 runtime
 reports the expected Crew and DSH versions.
 
+Both the update lock and the handoff lock record the owning process's start
+time alongside its PID, and a lock is reclaimed only when the PID is gone or
+when that PID is provably a different process than the one that took the lock.
+Without it, a recycled PID — the operating system handing a dead owner's PID to
+an unrelated process — made a stale lock look alive for as long as the stranger
+ran, and no contender could ever reclaim it. Where the platform cannot report a
+process start time the check falls back to the PID alone, so a lock is never
+stolen on a guess.
+
+The update transaction itself is an ordered state machine, recorded in the
+journal's `runtime.state` and advanced one checkpoint at a time:
+
+| State | Meaning |
+| --- | --- |
+| `before-stop` | Intent journaled; the owned runtime has not been touched |
+| `stopped` | A stop completed, so the runtime tree may be mutated |
+| `restarted` | A start was **initiated** — written before the start call |
+| `verified` | The candidate is running and its dual identity checked out |
+| `committed` | The release pointer moved; terminal |
+
+`restarted` is written before the start happens, on purpose: a crash between
+the start and the verification is then indistinguishable from a completed
+start, which is the safe direction. Recovery uses this to decide whether the
+runtime tree may be replaced at all — replacing it under a live process is the
+damage the record exists to prevent. Journals written by earlier versions
+(`staged`, `starting`) are still read under their new names.
+
 On Windows, installation registers login startup. To start immediately and
 open the Crew control:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "1.10.3",
+  "version": "1.10.5",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/skills/dsh-crew/SKILL.md

@@ -86,12 +86,27 @@ review asks for changes, that is a task result to act on — not approval.
 
 ## Common ways a dispatch surprises you
 
-- **A task that only asks a question fails.** The delivery contract wants a
-  change; a reply-only task returns `DELIVERY_INCOMPLETE`. That is the gate
-  working, not the worker failing.
+- **A task that only asks a question fails.** The delivery contract wants
+  auditable evidence, and a reply with neither a change nor a verified check is
+  incomplete. That is the gate working, not the worker failing. A task that
+  changes nothing *on purpose* can pass — see the next entry.
+- **A job is named `Crew_<date>_<time>_<purpose>`.** The worktree directory, the
+  session the Harness lists in its workspace panel, and the name in a status
+  payload all use that one string, so a conversation can be matched to a
+  directory by eye. The purpose is the role: `worker` or `reviewer`.
+- **A verified zero-change task needs `constraints.allow_no_changes: true`.**
+  For a deliberately temporary job — create, verify, clean up, end with an empty
+  diff — that flag plus the reported checks is what certifies it. It requires a
+  clean, readable baseline, at least one `PASS` and no `FAIL`, and it relaxes
+  nothing else: no evidence, a failed check, a dirty baseline or an actual change
+  each still refuse.
 - **Isolated workspaces need git.** The default `worktree` isolation fails with
   `NOT_GIT_REPOSITORY` for a non-git workspace rather than silently sharing the
-  tree. Use `shared` deliberately if that is what you want.
+  tree. Use `shared` deliberately if that is what you want; `allow_no_changes`
+  works in either.
+- **A repository with no commits cannot be isolated.** `git init` with nothing
+  committed reports `REPOSITORY_HAS_NO_COMMITS` — there is no revision to start
+  from. Commit once, or run that job with `shared`.
 - **Long tasks need a longer timeout.** `timeout_seconds` is per attempt and
   caps at 7200; the default is far shorter than a real refactor.
 - **A worker cannot see your conversation.** Anything it needs must be in

package/src/delivery.mjs

@@ -81,6 +81,27 @@ Then stop and return control to the Main Agent.
 Do not autonomously start a new task or delegate further work.` : ''}`;
 }
 
+/** A prompt that already carries the job identity header (added once). */
+export const JOB_HEADER_MARKER = 'Crew job ';
+
+/**
+ * Open the prompt with the job's Crew name.
+ *
+ * The Harness lists a dispatched job in its workspace panel under a title it
+ * derives from the opening words of the first message the agent receives, so
+ * without this a Crew job appears as "In this isolated git repository," or
+ * whatever the task happened to begin with — while its worktree is named
+ * `Crew_<date>_<time>_<purpose>`. Prefixing the name makes all three agree, and
+ * makes a job findable in that list by the same string an operator already uses
+ * on disk. Idempotent, so a re-dispatch or a review prompt is not doubled.
+ */
+export function prependJobIdentity(task, { name, role } = {}) {
+  if (typeof task !== 'string' || !name) return task;
+  if (task.startsWith(JOB_HEADER_MARKER)) return task;
+  const roleSuffix = role ? ` — role: ${role}` : '';
+  return `${JOB_HEADER_MARKER}${name}${roleSuffix}\n\n${task}`;
+}
+
 /**
  * Append the delivery instructions to a worker task prompt. Idempotent: a task
  * that already carries the delivery report (e.g. a review prompt, or a
@@ -92,16 +113,55 @@ export function appendDeliveryInstructions(task, { tier, isReview } = {}) {
   return `${task}\n\n${buildDeliveryInstructions({ tier, isReview })}`;
 }
 
-function parseTestsSection(value) {
-  if (typeof value !== 'string' || value.trim() === '') return { valid: false, status: undefined };
-  const statuses = [];
-  for (const line of value.split(/\r?\n/).map((item) => item.trim()).filter(Boolean)) {
-    const match = line.match(/^(?:[-*+]\s+)?(PASS|FAIL|NOT RUN)\s+—\s+\S.*?\s+—\s+\S.*$/);
-    if (!match) return { valid: false, status: undefined };
-    statuses.push(match[1]);
+/**
+ * Parse one Tests entry, or null when the line is not one.
+ *
+ * The canonical form is `STATUS — <check> — <result>`; a model often writes it as
+ * a Markdown table row instead, and both are read here. This is deliberately
+ * forgiving about *noise* — a heading, a note, a wrapped continuation line — and
+ * strict about *evidence*: a line with no auditable state, or a bare `PASS` with
+ * nothing after it, is not an entry.
+ *
+ * The earlier revision marked the whole section invalid as soon as one line
+ * failed to match, so a single trailing note made a report with several PASS rows
+ * count as having no Tests section at all — delivery incomplete, task blocked —
+ * while a second, looser parser in `workflow.mjs` had already populated the
+ * visible evidence. Two parsers gave two answers about one section; there is now
+ * one, and it lives here.
+ */
+export function parseTestRow(line) {
+  const normalized = String(line ?? '')
+    .replace(/^\s*[-*+]\s+/, '')
+    .replace(/^\|/, '')
+    .replace(/\|\s*$/, '')
+    .trim();
+  const match = /^(PASS|FAIL|NOT RUN)\b(.*)$/i.exec(normalized);
+  if (!match) return null;
+  const parts = match[2]
+    .split(/\s*(?:—|\||\t)\s*/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  // A state on its own is not evidence, and neither is a bare check: the contract
+  // asks for what was checked *and* what happened.
+  if (parts.length < 2) return null;
+  return { status: match[1].toUpperCase(), command: parts[0], summary: parts.slice(1).join(' — ') };
+}
+
+/**
+ * The auditable state of a Tests section plus the entries it contains. `valid`
+ * means at least one entry was readable; it does not mean every line was.
+ */
+export function parseTestsSection(value) {
+  if (typeof value !== 'string' || value.trim() === '') return { valid: false, status: undefined, tests: [] };
+  const tests = [];
+  for (const line of value.split(/\r?\n/)) {
+    const row = parseTestRow(line);
+    if (row) tests.push(row);
   }
-  const status = statuses.includes('FAIL') ? 'FAIL' : statuses.includes('NOT RUN') ? 'NOT RUN' : statuses.includes('PASS') ? 'PASS' : undefined;
-  return { valid: status !== undefined, status };
+  if (tests.length === 0) return { valid: false, status: undefined, tests: [] };
+  const statuses = tests.map((test) => test.status);
+  const status = statuses.includes('FAIL') ? 'FAIL' : statuses.includes('NOT RUN') ? 'NOT RUN' : 'PASS';
+  return { valid: true, status, tests };
 }
 
 /**

package/src/hub/index.mjs

@@ -5,7 +5,7 @@
 
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, isAbsolute, resolve as resolvePath } from 'node:path';
+import { dirname, join, isAbsolute, resolve as resolvePath, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { createShardWriter, readMergedStatus } from '../status-shard.mjs';
 import {
@@ -19,7 +19,7 @@ import {
 import { buildDirectSelectionTrace, resolveWorkerModel, resolveModel } from '../model-routing.mjs';
 import { scheduleAdmission } from '../model-schedule.mjs';
 import { readHarnessModelCatalog } from '../model-catalog.mjs';
-import { appendDeliveryInstructions, parseDeliveryReport, formatDeliveryMetadata } from '../delivery.mjs';
+import { appendDeliveryInstructions, prependJobIdentity, parseDeliveryReport, formatDeliveryMetadata } from '../delivery.mjs';
 import { captureWorkspaceBaseline, captureWorkspaceDiff, NOT_A_GIT_REPOSITORY } from '../workspace-audit.mjs';
 import { applyWorkspaceEvidence, buildOutcome, JOB_PHASES } from '../workflow.mjs';
 import { boundedMachineCodeFromError } from '../structured-error-code.mjs';
@@ -28,7 +28,8 @@ import { getHubRuntimeIdentity } from '../runtime-identity.mjs';
 import { loadRoleProfiles, resolveRoleProfile, saveRoleProfiles } from '../role-profiles.mjs';
 import { addContextReferences, buildWorkspaceTask, isSafeBranchName, loadWorkspaceContexts, resolveWorkspaceContext, saveWorkspaceContexts } from '../workspace-context.mjs';
 import { buildExtensionContract } from '../extension-contract.mjs';
-import { cleanupIsolatedWorkspace, createIsolatedWorkspace } from '../workspace-isolation.mjs';
+import { cleanupIsolatedWorkspace, createIsolatedWorkspace, isCrewWorktreeName } from '../workspace-isolation.mjs';
+import { jobDisplayName } from '../job-identity.mjs';
 import { assessWorkspaceReadiness } from '../workspace-readiness.mjs';
 import { buildConfigReadinessMatrix } from '../config-readiness.mjs';
 import { localRequestCore, originLoopback } from '../local-request-guard.mjs';
@@ -499,6 +500,7 @@ export function hubCanonicalEvents(job = {}) {
 // ---------- job registry ----------
 
 export function applyHubWorkspaceEvidence({ outcome, workspaceDiff, allowNoChanges = false, isolation = 'shared', role = 'worker' } = {}) {
+  void isolation;
   const changes = workspaceDiff?.changes ?? {};
   const hasChanges = ['modified', 'deleted', 'renamed', 'untracked']
     .some((key) => Array.isArray(changes[key]) && changes[key].length > 0);
@@ -506,7 +508,14 @@ export function applyHubWorkspaceEvidence({ outcome, workspaceDiff, allowNoChang
   return applyWorkspaceEvidence(outcome, {
     evidenceAvailable,
     hasChanges,
-    allowNoChanges: allowNoChanges === true && isolation === 'worktree',
+    // `allow_no_changes` is the caller's explicit authorization, and `shared` is an
+    // ordinary way to run: requiring a worktree here meant an authorized
+    // zero-change task in a shared workspace could never be verified as one, and
+    // was downgraded to partial. Reliability is guarded by `evidenceAvailable`,
+    // which `applyWorkspaceEvidence` already requires — a dirty or unreadable
+    // baseline grants no authorization and the task stays unverified. The
+    // standalone path never had this condition, so the two disagreed.
+    allowNoChanges: allowNoChanges === true,
     requireNoChangeAuthorization: role === 'worker',
   });
 }
@@ -823,7 +832,6 @@ export class WorkerRegistry {  constructor(ctx) {
     // it already carries one), so its final message follows ## Diff / ## Tests
     // / ## Risks — or the review contract for reviewer-role jobs.
     const jobRole = hasRole ? role : (delivery === 'review' || role === 'reviewer' ? 'reviewer' : 'worker');
-    const workerPrompt = appendDeliveryInstructions(task, { tier: effTier, role: jobRole, isReview: delivery === 'review' || jobRole === 'reviewer' });
 
     const id = `hub-${this.nextId++}-${Date.now().toString(36)}`;
 
@@ -839,11 +847,21 @@ export class WorkerRegistry {  constructor(ctx) {
     let executionCwd = cwd;
     let isolatedWorkspace = null;
     if ((requested_isolation === 'worktree' && jobRole === 'worker') || requested_isolation === 'readonly') {
-      const created = await createIsolatedWorkspace({ cwd, jobId: id, baseRevision: workspace_branch });
+      const created = await createIsolatedWorkspace({ cwd, jobId: id, purpose: jobRole, baseRevision: workspace_branch });
       if (!created.ok) throw Object.assign(new Error(created.error ?? created.reason), { code: created.reason });
       executionCwd = created.worktreePath;
       isolatedWorkspace = { worktreePath: created.worktreePath, repoRoot: created.repoRoot };
     }
+    // The Harness titles the session from the opening words of the prompt the
+    // agent receives, so the prompt opens with the job's Crew name: that makes the
+    // conversation, the worktree directory and the name an operator types the same
+    // string. An allocated worktree's name wins, so a collision suffix stays
+    // consistent between the two.
+    const jobName = isCrewWorktreeName(basename(executionCwd))
+      ? basename(executionCwd)
+      : jobDisplayName({ purpose: jobRole });
+    const workerPrompt = appendDeliveryInstructions(prependJobIdentity(task, { name: jobName, role: jobRole }), { tier: effTier, role: jobRole, isReview: delivery === 'review' || jobRole === 'reviewer' });
+
     const sessionId = `session-${randomUUID()}`;
     // Record provenance while it is still knowable: a session header carries no
     // field naming who asked for the session, so a later Crew-scoped cleanup can

package/src/install/npx-lifecycle.mjs

@@ -43,6 +43,8 @@ import * as realInstaller from './install.mjs';
 import { samePayloadContent, capturePayloadContent } from './payload-content.mjs';
 import { crewDshHome, crewProfileDir } from './install.mjs';
 import { releaseClaimsState } from '../release-in-use.mjs';
+import { compareProcessToken, processStartToken } from '../process-identity.mjs';
+import { checkRuntimeAdvance, normalizeRuntimeState, runtimeStateMayHaveStarted } from './runtime-lifecycle.mjs';
 import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration, migrateCrewDshRuntime, installDshInto, restoreRetainedRuntime, crewDshRuntimeRoot, payloadDshVersion, TARGET_DSH_VERSION } from '../dsh-cli-runtime.mjs';
 import {
   ensureOfficialWebIntegration,
@@ -254,7 +256,13 @@ export function acquireUpdateLock({ home = homedir() } = {}) {
   const file = updateLockFile({ home });
   mkdirSync(dirname(file), { recursive: true });
   const nonce = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-  const record = { pid: process.pid, started_at: isoNow(), nonce, hostname: process.env.COMPUTERNAME ?? null };
+  const record = {
+    pid: process.pid,
+    started_at: isoNow(),
+    nonce,
+    hostname: process.env.COMPUTERNAME ?? null,
+    process_start_token: processStartToken(process.pid),
+  };
   try {
     writeFileSync(file, JSON.stringify(record) + '\n', { flag: 'wx' });
     return { ok: true, owner: true, nonce };
@@ -271,12 +279,16 @@ function lockOwnerAlive(record) {
   if (!Number.isInteger(pid) || pid < 1) return false;
   try {
     process.kill(pid, 0);
-    return true;
   } catch (error) {
     // ESRCH = no such process (dead owner, safe to reclaim).
     // EPERM = process exists but we cannot signal it (live owner, keep).
     return error?.code !== 'ESRCH';
   }
+  // The pid exists — but is it still the process that took the lock? A recycled
+  // pid answers "yes" to `kill(pid, 0)` and left a stale lock looking alive
+  // until the unrelated process exited, which is a lock nobody can reclaim.
+  // The recorded start token decides; without one we keep the PID-only verdict.
+  return compareProcessToken(record) !== 'different';
 }
 
 // Stale-lock reclaim with a single atomic claim: each contender writes its
@@ -292,7 +304,7 @@ function lockOwnerAlive(record) {
 function tryReclaimUpdateLock({ home, record }) {
   const file = updateLockFile({ home });
   const arbitrationPath = `${file}.arbitration`;
-  const myClaim = { pid: process.pid, nonce: record.nonce, started_at: isoNow() };
+  const myClaim = { pid: process.pid, nonce: record.nonce, started_at: isoNow(), process_start_token: processStartToken(process.pid) };
   for (let round = 0; round < 3; round += 1) {
     let current = null;
     try { current = JSON.parse(readFileSync(file, 'utf8')); } catch { current = null; }
@@ -812,17 +824,17 @@ export async function reconcileUpdateJournal({ home = homedir(), log = () => {},
       const liveVersion = readRuntimeTreeVersionSync(rt.liveRoot);
       if (liveVersion !== rt.priorVersion) {
         // The tree has to be replaced, and replacing it under a running process is
-        // the damage. The journal says whether a start can have happened: it is
-        // set to `starting` before the candidate is started and to `verified`
-        // after it checks out, so anything else means no runtime was ever started
-        // from the candidate cohort and the swap is safe.
+        // the damage. The journal says whether a start can have happened: the
+        // lifecycle records `restarted` before the candidate is started and
+        // `verified` after it checks out, so anything before that means no runtime
+        // was ever started from the candidate cohort and the swap is safe.
         //
-        // `starting` cannot be resolved from the journal alone — the candidate may
+        // `restarted` cannot be resolved from the journal alone — the candidate may
         // be live and unverified. It must not be a dead end either, so recovery
         // stops the runtime and rolls back on a stop that actually happened, or on
         // a durable STOPPED session that already proves one did. Anything less is
         // not proof: a runtime that cannot be shown to be stopped keeps its tree.
-        if (rt.state === 'starting') {
+        if (runtimeStateMayHaveStarted(rt.state)) {
           const window = await openMaintenanceWindow({ home, journal });
           if (window?.malformed) {
             return { ok: false, code: 'JOURNAL_MAINTENANCE_SESSION_MALFORMED', stage: journal.stage, error: `${window.error}; refusing to replace a runtime tree while a stopped runtime cannot be accounted for` };
@@ -2332,7 +2344,7 @@ export async function performCoordinatedCohortUpdate({
     prior: { name: prior.name, version: prior.version, path: prior.path, dshVersion: priorDshVersion },
     candidate: { name: candidateManifest.name, version: candidateManifest.version, stageDir, dshVersion: candidateDshVersion },
     runtime: {
-      state: 'staged',
+      state: 'before-stop',
       liveRoot,
       priorRoot: prevPath,
       priorVersion: priorDshVersion,
@@ -2402,9 +2414,20 @@ export async function performCoordinatedCohortUpdate({
     // session then refused the next ordinary stop, so the machine could not
     // recover on its own. `startOwnedBackend` accepts this exact lease and
     // runtime id, which is what recovery needs to close the window.
-    if (stopped.lease && stopped.runtime_id) {
-      writeUpdateJournal({ ...journalBase, runtime: { ...journalBase.runtime, maintenance: { lease: stopped.lease, runtime_id: stopped.runtime_id } } });
+    // The `stopped` checkpoint is recorded whether or not the supervisor handed
+    // back a maintenance lease: a stop that succeeded is a stopped runtime
+    // either way, and the state machine needs that fact before the tree is
+    // touched. The lease is an additional capability, not the checkpoint.
+    const stopAdvance = checkRuntimeAdvance(journalBase.runtime.state, 'stopped');
+    if (!stopAdvance.ok) {
+      clearUpdateJournal({ home });
+      return { ok: false, code: stopAdvance.code, error: stopAdvance.error };
     }
+    const maintenance = stopped.lease && stopped.runtime_id ? { lease: stopped.lease, runtime_id: stopped.runtime_id } : null;
+    writeUpdateJournal({
+      ...journalBase,
+      runtime: { ...journalBase.runtime, state: 'stopped', ...(maintenance ? { maintenance } : {}) },
+    });
     let liveMoved = false;
     try {
       // Move live runtime aside, retaining its tree for offline rollback.
@@ -2441,12 +2464,18 @@ export async function performCoordinatedCohortUpdate({
       const comp = await compensate();
       return finalizeCompensationFailure({ home, code: null, error: 'candidate activation failed', comp });
     }
-    // Record that a start may be about to happen BEFORE it happens. Recovery
-    // decides whether the runtime tree can be replaced by reading this, and a
-    // crash between the start and the verification would otherwise look exactly
-    // like "the candidate was never started" — which is how a rollback ends up
-    // swapping the tree out from under a running process.
-    writeUpdateJournal({ ...journalBase, runtime: { ...journalBase.runtime, state: 'starting' } });
+    // Record that a start is about to happen BEFORE it happens. This is the
+    // `restarted` checkpoint, and it is written pre-emptively on purpose:
+    // recovery decides whether the runtime tree can be replaced by reading it,
+    // and a crash between the start and the verification would otherwise look
+    // exactly like "the candidate was never started" — which is how a rollback
+    // ends up swapping the tree out from under a running process.
+    const startAdvance = checkRuntimeAdvance('stopped', 'restarted');
+    if (!startAdvance.ok) {
+      const comp = await compensate().catch(() => ({ ok: false }));
+      return finalizeCompensationFailure({ home, code: startAdvance.code, error: startAdvance.error, comp });
+    }
+    writeUpdateJournal({ ...journalBase, runtime: { ...journalBase.runtime, state: 'restarted' } });
     const started = await startFn();
     if (started?.ok !== true) {
       const comp = await compensate();
@@ -2500,6 +2529,10 @@ export async function performCoordinatedCohortUpdate({
     // COMMIT POINT / LAST: pointer write after the verified journal.
     switchPointer(candidateRelease);
 
+    // The pointer write IS the commit, so this only records that it happened.
+    // A failure here must never roll a committed update back — the pointer is
+    // the ground truth and recovery re-derives the outcome from it either way.
+    markJournalCommitted({ home });
     clearUpdateJournal({ home });
     log(`✓ coordinated update committed: Crew ${candidateManifest.version} + DSH ${candidateDshVersion}`);
     return { ok: true, version: candidateManifest.version, path: stageDir, dsh_version: candidateDshVersion, restarted: started };
@@ -2509,6 +2542,25 @@ export async function performCoordinatedCohortUpdate({
   }
 }
 
+// Records the terminal lifecycle state. Deliberately non-fatal and deliberately
+// after the pointer write: by the time this runs the update is committed, so a
+// failure to annotate must not become a failure to update.
+function markJournalCommitted({ home }) {
+  try {
+    const file = updateJournalFile({ home });
+    if (!existsSync(file)) return { ok: false, code: 'JOURNAL_ABSENT' };
+    const journal = JSON.parse(readFileSync(file, 'utf8'));
+    const rt = journal?.runtime;
+    if (!rt || typeof rt !== 'object') return { ok: false, code: 'JOURNAL_RUNTIME_ABSENT' };
+    const advance = checkRuntimeAdvance(rt.state, 'committed');
+    if (!advance.ok) return advance;
+    writeFileAtomic(file, JSON.stringify({ ...journal, runtime: { ...rt, state: 'committed', committed_at: isoNow() } }, null, 2) + '\n');
+    return { ok: true };
+  } catch {
+    return { ok: false, code: 'JOURNAL_COMMIT_MARK_FAILED' };
+  }
+}
+
 // Shared failure exit for a compensated coordinated transaction. The journal
 // is cleared ONLY when compensation fully succeeded (prior payload
 // activated, prior runtime restored, restart + dual verify passed). When

package/src/install/runtime-lifecycle.mjs

@@ -0,0 +1,87 @@
+// The coordinated-update runtime lifecycle, as one ordered state machine.
+//
+// The update transaction stops the owned 3210, swaps its runtime tree, starts
+// the candidate, verifies a dual identity and only then moves the release
+// pointer. Every one of those steps can be interrupted by a crash or a power
+// loss, and what recovery is allowed to do afterwards depends entirely on how
+// far the transaction got — in particular on whether a start *may* already have
+// happened, because replacing a runtime tree under a live process is the damage
+// this whole path exists to avoid.
+//
+// That question used to be answered by a state written at the last moment
+// before the start, which left the earlier part of the transaction implicit:
+// "no state recorded" and "state recorded but nothing done yet" were the same
+// thing, and there was no name at all for the committed end. This module names
+// all five checkpoints and rejects any write that would skip or rewind one, so
+// the journal on disk is always a record of a transaction that actually
+// followed this order.
+
+export const RUNTIME_LIFECYCLE_STATES = Object.freeze([
+  'before-stop', // Intent is journaled; the owned runtime has not been touched.
+  'stopped', // A durable maintenance window is open; mutating the tree is authorized.
+  'restarted', // A start has been INITIATED — written before the start call, so a
+  //             crash in flight is indistinguishable from a completed start.
+  //             That ambiguity is deliberate: it is the safe direction, and it
+  //             means "the live runtime may already be the candidate".
+  'verified', // Candidate is running and its dual identity checked out.
+  'committed', // Release pointer moved. Terminal.
+]);
+
+// Exactly one forward edge is legal between neighbouring checkpoints. A
+// multi-step jump would describe work that never recorded its intermediate
+// proof, and a rewind would rewrite history recovery has already acted on.
+export const RUNTIME_LIFECYCLE_TRANSITIONS = Object.freeze({
+  'before-stop': Object.freeze(['stopped']),
+  stopped: Object.freeze(['restarted']),
+  restarted: Object.freeze(['verified']),
+  verified: Object.freeze(['committed']),
+  committed: Object.freeze([]),
+});
+
+// Journals written by earlier versions used different names for the first two
+// checkpoints. They are read, never written.
+const LEGACY_RUNTIME_STATES = Object.freeze({ staged: 'before-stop', starting: 'restarted' });
+
+export function normalizeRuntimeState(state) {
+  if (typeof state !== 'string' || state === '') return null;
+  const mapped = LEGACY_RUNTIME_STATES[state] ?? state;
+  return RUNTIME_LIFECYCLE_STATES.includes(mapped) ? mapped : null;
+}
+
+export function runtimeLifecycleIndex(state) {
+  const normalized = normalizeRuntimeState(state);
+  return normalized === null ? -1 : RUNTIME_LIFECYCLE_STATES.indexOf(normalized);
+}
+
+// The only question recovery must never get wrong. Anything from `restarted`
+// onward means a start was initiated; `before-stop` and `stopped` mean the
+// candidate tree has never been handed to a process.
+export function runtimeStateMayHaveStarted(state) {
+  return runtimeLifecycleIndex(state) >= RUNTIME_LIFECYCLE_STATES.indexOf('restarted');
+}
+
+export function canAdvanceRuntimeState(from, to) {
+  const current = normalizeRuntimeState(from);
+  const next = normalizeRuntimeState(to);
+  if (current === null || next === null) return false;
+  return RUNTIME_LIFECYCLE_TRANSITIONS[current].includes(next);
+}
+
+export function checkRuntimeAdvance(from, to) {
+  const current = normalizeRuntimeState(from);
+  const next = normalizeRuntimeState(to);
+  if (current === null) {
+    return { ok: false, code: 'RUNTIME_LIFECYCLE_UNKNOWN_STATE', error: `unrecognized runtime lifecycle state ${JSON.stringify(from)}` };
+  }
+  if (next === null) {
+    return { ok: false, code: 'RUNTIME_LIFECYCLE_UNKNOWN_STATE', error: `unrecognized runtime lifecycle state ${JSON.stringify(to)}` };
+  }
+  if (!RUNTIME_LIFECYCLE_TRANSITIONS[current].includes(next)) {
+    return {
+      ok: false,
+      code: 'RUNTIME_LIFECYCLE_INVALID_TRANSITION',
+      error: `runtime lifecycle cannot go ${current} -> ${next}`,
+    };
+  }
+  return { ok: true, from: current, to: next };
+}

package/src/install/windows-supervisor-lifecycle.mjs

@@ -8,6 +8,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { compareProcessToken, processStartToken } from '../process-identity.mjs';
 
 export const WINDOWS_SUPERVISOR_HANDOFF_SCHEMA = 1;
 export const WINDOWS_SUPERVISOR_HANDOFF_PHASES = Object.freeze([
@@ -193,7 +194,11 @@ export function clearWindowsSupervisorHandoffJournal({ appRoot, journalFile, han
 function defaultAcquireLock({ journalFile, now }) {
   const file = `${journalFile}.lock`;
   const token = randomUUID();
-  const record = { schema_version: 1, token, pid: process.pid, acquired_at: now };
+  // Same PID-reuse hazard as the update lock: the lock is reclaimed by asking
+  // whether its pid exists, so a recycled pid keeps a dead owner's lock alive.
+  // The start token makes the pair an identity; the probe is Windows-only here
+  // because this lock only ever guards the Windows supervisor handoff.
+  const record = { schema_version: 1, token, pid: process.pid, acquired_at: now, process_start_token: processStartToken(process.pid) };
   const tryCreate = () => {
     const pending = `${file}.pending.${process.pid}.${randomUUID()}`;
     try {
@@ -234,10 +239,10 @@ function lockOwnerAlive(record) {
   if (!Number.isInteger(pid) || pid < 1) return false;
   try {
     process.kill(pid, 0);
-    return true;
   } catch (error) {
     return error?.code !== 'ESRCH';
   }
+  return compareProcessToken(record) !== 'different';
 }
 
 function reclaimDefaultLock({ file }) {

package/src/job-identity.mjs

@@ -0,0 +1,39 @@
+// The one name a Crew job is known by.
+//
+// A job has three identities an operator sees: the worktree directory, the
+// conversation the Harness lists in its workspace panel, and whatever the host
+// integration shows. Each of them is derived from something different — the
+// worktree from the name Crew allocates, the conversation from the opening words
+// of the first message the agent receives — so they only agree if they are built
+// from the same string. This module is that string.
+//
+// The shape is `Crew_<YYYYMMDD>_<HHMMSS>_<purpose>`, matching the worktree naming
+// rule; `src/workspace-isolation.mjs` allocates worktrees in the same shape, and a
+// test asserts that every name produced here satisfies its ownership grammar, so
+// the two cannot drift apart silently.
+
+export const JOB_NAME_PREFIX = 'Crew_';
+export const JOB_PURPOSE_MAX = 32;
+
+export const JOB_NAME_RE = /^Crew_\d{8}_\d{6}_[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*(?:-\d+)?$/;
+
+/** Local wall-clock stamp: readable, and what an operator expects to see. */
+export function jobNameStamp(at) {
+  const d = at instanceof Date ? at : new Date(at ?? Date.now());
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}`
+    + `_${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/** A purpose reduced to something safe to put in a path and a heading. */
+export function jobNamePurpose(purpose, max = JOB_PURPOSE_MAX) {
+  // Truncate before trimming: trimming first lets the slice end on the separator
+  // it just created, and the name then fails the grammar above.
+  return String(purpose ?? 'job').replace(/[^A-Za-z0-9]+/g, '-')
+    .slice(0, max).replace(/^-+|-+$/g, '') || 'job';
+}
+
+/** `Crew_<date>_<time>_<purpose>` for a job starting at `at`. */
+export function jobDisplayName({ purpose, at } = {}) {
+  return `${JOB_NAME_PREFIX}${jobNameStamp(at)}_${jobNamePurpose(purpose)}`;
+}

package/src/jobs.mjs

@@ -12,9 +12,11 @@ import { createStandaloneHarness } from './standalone-sdk.mjs';
 import { readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { createShardWriter } from './status-shard.mjs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, basename } from 'node:path';
 import { homedir } from 'node:os';
-import { appendDeliveryInstructions, parseDeliveryReport, formatDeliveryMetadata } from './delivery.mjs';
+import { appendDeliveryInstructions, prependJobIdentity, parseDeliveryReport, formatDeliveryMetadata } from './delivery.mjs';
+import { jobDisplayName } from './job-identity.mjs';
+import { isCrewWorktreeName } from './workspace-isolation.mjs';
 import { captureWorkspaceBaseline, captureWorkspaceDiff, NOT_A_GIT_REPOSITORY } from './workspace-audit.mjs';
 import { buildOutcome, JOB_PHASES } from './workflow.mjs';
 import { raceWaiters } from './removable-waiter.mjs';
@@ -134,7 +136,14 @@ export function startJob({
   // The worker always gets the auditable Delivery Contract appended (unless it
   // already carries one), so its final message follows ## Diff / ## Tests /
   // ## Risks — or the review contract for reviewer-role jobs.
-  const workerPrompt = appendDeliveryInstructions(task, { tier, role, isReview: delivery === 'review' });
+  //
+  // It also opens with the job's Crew name, for the same reason the Hub does it:
+  // the Harness titles the session from the opening words of this prompt, so a
+  // standalone job should be as findable in that list as an isolated one.
+  const jobName = isCrewWorktreeName(basename(workspace))
+    ? basename(workspace)
+    : jobDisplayName({ purpose: role });
+  const workerPrompt = appendDeliveryInstructions(prependJobIdentity(task, { name: jobName, role }), { tier, role, isReview: delivery === 'review' });
   const id = `job-${nextId++}-${Date.now().toString(36)}`;
   const dotEnv = loadDotEnv();
   if (!process.env.DEEPSEEK_API_KEY && !dotEnv.DEEPSEEK_API_KEY) {

package/src/process-identity.mjs

@@ -0,0 +1,74 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+// A PID is not an identity. Windows and Linux both recycle them, so a lock
+// record that carries only `pid` can describe a dead owner and a live stranger
+// at the same time — and `process.kill(pid, 0)` cannot tell those apart, because
+// the only question it answers is "does some process have this pid". That is
+// precisely the question that made a stale lock look alive, so liveness needs a
+// second field: the start time of the process. The Windows supervisor already
+// proves its own identity with `StartTime.ToUniversalTime().Ticks`, and this is
+// the same value read from Node.
+//
+// The probe is best-effort by construction. When the platform cannot answer,
+// every caller falls back to its PID-only verdict rather than inventing one.
+
+const cache = new Map();
+
+export function processStartToken(pid, { probe = defaultProbe } = {}) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n < 1) return null;
+  if (cache.has(n)) return cache.get(n);
+  let token = null;
+  try { token = probe(n); } catch { token = null; }
+  if (typeof token !== 'string' || token === '') token = null;
+  cache.set(n, token);
+  return token;
+}
+
+export function resetProcessStartTokenCache() {
+  cache.clear();
+}
+
+// 'same'      — the pid exists and it is provably still the recorded process.
+// 'different' — the pid exists but belongs to a different process (recycled PID).
+// 'unknown'   — no token on record, or the platform could not answer. Callers
+//               must treat this as "cannot prove the owner is gone".
+export function compareProcessToken(record, { probe = defaultProbe } = {}) {
+  const recorded = record?.process_start_token ?? record?.processStartToken ?? null;
+  if (typeof recorded !== 'string' || recorded === '') return 'unknown';
+  const current = processStartToken(record?.pid, { probe });
+  if (current === null) return 'unknown';
+  return current === recorded ? 'same' : 'different';
+}
+
+function defaultProbe(pid) {
+  if (process.platform === 'win32') return windowsStartToken(pid);
+  if (process.platform === 'linux') return linuxStartToken(pid);
+  return null;
+}
+
+function windowsStartToken(pid) {
+  const out = execFileSync('powershell.exe', [
+    '-NoProfile', '-NonInteractive', '-Command',
+    `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
+  ], { timeout: 8000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+  const text = String(out ?? '').trim();
+  return /^\d+$/.test(text) ? `win-ticks:${text}` : null;
+}
+
+// `/proc/<pid>/stat` field 22 (starttime) counts clock ticks since boot, so it
+// is only unique *within* a boot. Pairing it with the boot id makes the token
+// unique across reboots too, which matters because the lock file outlives them.
+function linuxStartToken(pid) {
+  let stat;
+  try { stat = readFileSync(`/proc/${pid}/stat`, 'utf8'); } catch { return null; }
+  const close = stat.lastIndexOf(')');
+  if (close < 0) return null;
+  const fields = stat.slice(close + 1).trim().split(/\s+/);
+  const starttime = fields[19];
+  if (!/^\d+$/.test(String(starttime ?? ''))) return null;
+  let boot = '';
+  try { boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim(); } catch { boot = ''; }
+  return `linux-starttime:${boot}:${starttime}`;
+}

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '1.10.3';
+export const RUNTIME_VERSION = '1.10.5';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([

package/src/workflow.mjs

@@ -11,7 +11,7 @@
 // transport adapter.
 
 import { evaluateAttempt } from './policy.mjs';
-import { parseDeliveryReport } from './delivery.mjs';
+import { parseDeliveryReport, parseTestsSection } from './delivery.mjs';
 
 export const JOB_PHASES = Object.freeze({
   CREATED: 'created',
@@ -121,14 +121,9 @@ function parseChanges(section) {
   });
 }
 
-function parseTests(section) {
-  return splitSection(section).map((line) => {
-    const m = line.match(/^(?:[-*+]\s+)?(PASS|FAIL|NOT RUN)\s+—\s+(.+?)\s+—\s+(.+)$/);
-    if (!m) return { line };
-    const [, status, command, summary] = m;
-    return { status, command: command.trim(), summary: summary.trim() };
-  });
-}
+// The Tests section is parsed by the delivery contract's own parser. This module
+// used to carry a second, looser one, so one report could show PASS entries to the
+// caller while the delivery gate saw no Tests section at all.
 
 /**
  * Classify a worker run into a canonical task status. Completion of the
@@ -151,8 +146,11 @@ export function classifyTaskStatus({ executionStatus = 'completed', testsStatus,
  */
 export function buildOutcome({ result = '', deliveryMeta, executionStatus, stopReason, deliveryMissing } = {}) {
   const parsed = parseDeliveryReport(result);
-  const testsStatus = parsed.tests_status ?? deliveryMeta?.tests_status;
-  const tests = parseTests(parsed.sections.Tests);
+  // The aggregate status and the visible entries come from one parse, so they can
+  // no longer disagree about whether the Tests section is evidence.
+  const parsedTests = parseTestsSection(parsed.sections.Tests);
+  const testsStatus = parsedTests.status ?? parsed.tests_status ?? deliveryMeta?.tests_status;
+  const tests = parsedTests.tests;
   const execStatus = executionStatus ?? (stopReason === 'completed' ? 'completed' : 'failed');
   return {
     execution_status: execStatus,

package/src/workspace-isolation.mjs

@@ -25,6 +25,8 @@ export const NOT_GIT_REPOSITORY = 'NOT_GIT_REPOSITORY';
 export const GIT_NOT_FOUND = 'GIT_NOT_FOUND';
 export const GIT_TIMEOUT = 'GIT_TIMEOUT';
 export const GIT_ERROR = 'GIT_ERROR';
+/** A valid repository whose HEAD does not resolve because nothing is committed. */
+export const REPOSITORY_HAS_NO_COMMITS = 'REPOSITORY_HAS_NO_COMMITS';
 export const WORKTREE_LOCKED = 'WORKTREE_LOCKED';
 export const WORKTREE_RESERVE_FAILED = 'WORKTREE_RESERVE_FAILED';
 export const CANDIDATE_CAPTURE_FAILED = 'CANDIDATE_CAPTURE_FAILED';
@@ -269,7 +271,22 @@ export async function inspectRepository({ cwd, git, runner } = {}) {
     runGit(run, ['status', '--porcelain', '-uall'], { cwd }),
   ]);
   if (!root.ok) return { ok: false, reason: root.reason, error: root.error };
-  if (!head.ok) return { ok: false, reason: head.reason, error: head.error };
+  if (!head.ok) {
+    // A repository with no commits yet is a valid repository whose HEAD simply
+    // does not resolve, and it cannot be told apart from a broken one by that
+    // command alone. It is worth telling apart: `git init && <ask Crew to do
+    // something>` is how a new project starts, and reporting it as a generic git
+    // error leaves the operator with nothing to act on.
+    const verified = await runGit(run, ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd });
+    if (verified.ok === false && (verified.code === 1 || verified.code === 128) && !verified.stdout?.trim()) {
+      return {
+        ok: false,
+        reason: REPOSITORY_HAS_NO_COMMITS,
+        error: 'this repository has no commits yet, so there is no revision for an isolated job to start from; make an initial commit, or set execution.isolation to "shared" to run in the working tree',
+      };
+    }
+    return { ok: false, reason: head.reason, error: head.error };
+  }
   return {
     ok: true,
     repoRoot: resolve(root.stdout.trim()),