great-cto 3.75.9 → 3.76.0

package/board/scripts/lib/workspace.mjs

@@ -0,0 +1,277 @@
+/**
+ * workspace — one task, one worktree (ADR-047, phase 1).
+ *
+ * This module decides; it does not act. It answers three questions and leaves
+ * the doing to the callers phase 3 adds:
+ *
+ *   claimState      which of five states a task's workspace is in
+ *   archiveVerdict  whether a worktree may be removed
+ *   allocatePort    which port a workspace gets (the one thing written here)
+ *
+ * The rule throughout: a read that failed is not an empty answer. A worktree
+ * listing git would not give is not "no worktrees", so it does not lead to
+ * creating one. A status git would not give is not "clean", so it does not lead
+ * to removing one. Uncommitted and untracked agent output is in no index and no
+ * history; a removal built on a wrong "clean" cannot be undone.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { worktreePath, integrationRef } from './worktree-state.mjs';
+import { isLinkedWorktree, WORKSPACE_PORT_FIRST, WORKSPACE_PORT_LAST } from './handoff-state.mjs';
+
+const OPTS = { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] };
+const PROVENANCE_FILE = 'great-cto-workspace.json';
+const PROVENANCES = new Set(['created', 'adopted']);
+const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)*$/;
+
+/** A task id is used in a path and a branch name, so it must be safe as both. */
+export function validTaskId(id) {
+  return typeof id === 'string' && id.length <= 120 && TASK_ID.test(id) && !id.endsWith('.lock');
+}
+
+/** One git command in `dir`, as { ok, out, status }. `status` is the exit code; null after a timeout. */
+export function gitIn(dir, exec) {
+  return (...args) => {
+    try {
+      return { ok: true, out: String(exec('git', ['-C', dir, ...args], OPTS)).trim(), status: 0 };
+    } catch (e) {
+      return { ok: false, out: '', status: e.status ?? null };
+    }
+  };
+}
+
+function real(p) {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+}
+
+/** The host that already made this workspace, or null. Whoever made it removes it. */
+export function detectHost({ cwd, env = process.env, git, exists = fs.existsSync, commonRoot = null }) {
+  if (Object.keys(env).some((k) => k.startsWith('CONDUCTOR_'))) return { host: 'conductor', signal: 'CONDUCTOR_* in the environment' };
+  if (isLinkedWorktree(git)) {
+    // `.conductor/` alone proves nothing: a repository can commit it, and then the
+    // main checkout, shared with every session, would be adopted as a workspace.
+    if (commonRoot && exists(path.join(commonRoot, '.conductor'))) return { host: 'conductor', signal: '.conductor/ at the common root, in a linked worktree' };
+    return { host: 'linked-worktree', signal: 'git-dir differs from git-common-dir' };
+  }
+  if (`${cwd.split(path.sep).join('/')}/`.includes('/.claude/worktrees/')) return { host: 'claude-code', signal: 'path under .claude/worktrees' };
+  return null;
+}
+
+function parseWorktreeList(text) {
+  return String(text).split('\n\n').filter(Boolean).map((block) => ({
+    path: /^worktree (.+)$/m.exec(block)?.[1] || null,
+    branch: /^branch refs\/heads\/(.+)$/m.exec(block)?.[1] || null,
+  })).filter((w) => w.path);
+}
+
+/**
+ * Which of the five states a task's workspace is in. Creates nothing.
+ * { state: 'adopt' | 'reuse' | 'conflict' | 'create' | 'unavailable', ... }
+ */
+export function claimState({ taskId, cwd = process.cwd(), env = process.env, exec = execFileSync, exists = fs.existsSync }) {
+  const unavailable = (reason) => ({ state: 'unavailable', reason });
+  if (!validTaskId(taskId)) return unavailable('the task id cannot name a directory and a branch');
+
+  const git = gitIn(cwd, exec);
+  const common = git('rev-parse', '--path-format=absolute', '--git-common-dir');
+  if (!common.ok) return unavailable('not a git repository');
+  if (path.basename(common.out) !== '.git') return unavailable('cannot name the main checkout of this repository');
+  const root = real(path.dirname(common.out));
+
+  const host = detectHost({ cwd, env, git, exists, commonRoot: root });
+  if (host) {
+    const top = git('rev-parse', '--show-toplevel');
+    if (!top.ok) return unavailable('git would not name the current worktree');
+    return { state: 'adopt', path: top.out, branch: git('branch', '--show-current').out || null, ...host };
+  }
+
+  const listed = git('worktree', 'list', '--porcelain');
+  if (!listed.ok) return unavailable('git worktree list failed, so what exists is not known');
+  const worktrees = parseWorktreeList(listed.out);
+
+  const target = worktreePath(root, taskId);
+  const branch = 'task/' + taskId;
+  const conflict = (reason) => ({ state: 'conflict', path: target, branch, reason });
+  const known = worktrees.find((w) => real(w.path) === target);
+
+  if (exists(target)) {
+    if (!known) return conflict('the directory exists but git does not know it');
+    if (known.branch !== branch) return conflict('the worktree is on ' + (known.branch || 'a detached HEAD') + ', not ' + branch);
+    return { state: 'reuse', path: target, branch };
+  }
+  if (known) return conflict('git lists this worktree but its directory is gone');
+  const elsewhere = worktrees.find((w) => w.branch === branch);
+  if (elsewhere) return conflict(branch + ' is already checked out at ' + elsewhere.path);
+
+  if (!git('rev-parse', '--verify', '--quiet', 'HEAD').ok) return unavailable('the repository has no commits');
+  const from = integrationRef((args) => git(...args).out);
+  if (!from) return unavailable('no integration branch to start from');
+  const branchExists = git('rev-parse', '--verify', '--quiet', 'refs/heads/' + branch).ok;
+  return { state: 'create', path: target, branch, from, branchExists };
+}
+
+function provenancePath(dir, git) {
+  const where = git('rev-parse', '--git-path', PROVENANCE_FILE);
+  return where.ok && where.out ? path.resolve(dir, where.out) : null;
+}
+
+/**
+ * Records who made this worktree, in its private git directory: it never shows
+ * in `git status`, and it goes when the worktree goes.
+ */
+export function recordProvenance(dir, provenance, { taskId, exec = execFileSync, now = new Date() }) {
+  if (!PROVENANCES.has(provenance)) throw new Error('unknown provenance: ' + provenance);
+  const file = provenancePath(dir, gitIn(dir, exec));
+  if (!file) throw new Error('git would not name the worktree directory');
+  fs.writeFileSync(file, JSON.stringify({ provenance, taskId, at: now.toISOString() }) + '\n');
+}
+
+/** The recorded provenance, or null when there is none or it cannot be read. */
+export function readProvenance(dir, { exec = execFileSync } = {}) {
+  const file = provenancePath(dir, gitIn(dir, exec));
+  if (!file) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return PROVENANCES.has(parsed?.provenance) ? parsed : null;
+  } catch { return null; } // archiveVerdict refuses on null, so no read here ever permits a removal
+}
+
+/**
+ * May this worktree be removed? Only when we created it, it has no uncommitted
+ * or untracked file, and its HEAD is on the integration branch. Every other
+ * answer, including every probe that could not answer, is { remove: false }.
+ */
+export function archiveVerdict(dir, { exec = execFileSync } = {}) {
+  const refuse = (reason) => ({ remove: false, reason });
+  if (readProvenance(dir, { exec })?.provenance !== 'created') return refuse('great_cto did not create this worktree');
+
+  const git = gitIn(dir, exec);
+  const status = git('status', '--porcelain');
+  if (!status.ok) return refuse('could not read the worktree status');
+  if (status.out) return refuse('the worktree has uncommitted or untracked files');
+
+  const ref = integrationRef((args) => git(...args).out);
+  if (!ref) return refuse('no integration branch to check against');
+  const merged = git('merge-base', '--is-ancestor', 'HEAD', ref);
+  if (merged.status === 1) return refuse('HEAD is not merged into ' + ref);
+  if (!merged.ok) return refuse('could not check whether HEAD is merged');
+  return { remove: true, ref };
+}
+
+/** The port a task tries first: the same one every time. */
+export function preferredPort(taskId) {
+  const size = WORKSPACE_PORT_LAST - WORKSPACE_PORT_FIRST + 1;
+  return WORKSPACE_PORT_FIRST + (createHash('sha256').update(taskId).digest().readUInt32BE(0) % size);
+}
+
+/** Pids listening on a port; [] when nobody is; null when lsof could not say. */
+export function listeners(port, { exec = execFileSync } = {}) {
+  try {
+    const out = String(exec('lsof', ['-nP', '-iTCP:' + port, '-sTCP:LISTEN', '-t'], OPTS));
+    return out.split('\n').filter(Boolean).map(Number);
+  } catch (e) {
+    return e.status === 1 ? [] : null; // lsof exits 1 when it finds nothing
+  }
+}
+
+function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+export function portsFile(env = process.env) {
+  return env.GREAT_CTO_PORTS_FILE || path.join(os.homedir(), '.great_cto', 'ports.json');
+}
+
+/** Claims in the file, or { refused } when the file exists and cannot be trusted. */
+function readClaims(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch (e) {
+    return e.code === 'ENOENT' ? { claims: [] } : { refused: 'could not read the file: ' + e.code };
+  }
+  let parsed;
+  try { parsed = JSON.parse(text); } catch (e) { return { refused: 'not valid JSON: ' + e.message }; }
+  if (!Array.isArray(parsed?.claims)) return { refused: 'no claims[] list' };
+  if (!parsed.claims.every((c) => c && typeof c.taskId === 'string' && Number.isInteger(c.port))) return { refused: 'a claim is malformed' };
+  return { claims: parsed.claims };
+}
+
+/**
+ * Gives a task its port and records the claim. The file says who claimed what;
+ * what is listening decides whether a port is actually free.
+ * { state: 'allocated' | 'reused' | 'refused' | 'exhausted' | 'failed', port?, file, reason? }
+ */
+export function allocatePort({
+  taskId, path: workspace, pid = process.pid, env = process.env, now = new Date(),
+  isAlive = processAlive, listening = (port) => listeners(port),
+}) {
+  const file = portsFile(env);
+  const refused = (reason) => ({ state: 'refused', file, reason });
+  if (!validTaskId(taskId)) return refused('the task id is not valid');
+  const read = readClaims(file);
+  if (read.refused) return refused(read.refused);
+
+  const couldNotCheck = (port) => refused('could not check who is listening on port ' + port);
+  const own = read.claims.find((c) => c.taskId === taskId);
+  let port = null;
+  let state = 'allocated';
+  if (own) {
+    const held = isAlive(own.pid) ? [] : listening(own.port);
+    if (held === null) return couldNotCheck(own.port);
+    if (!held.length) { port = own.port; state = 'reused'; }
+  }
+  const dropped = new Set();
+  if (port === null) {
+    const size = WORKSPACE_PORT_LAST - WORKSPACE_PORT_FIRST + 1;
+    const start = preferredPort(taskId) - WORKSPACE_PORT_FIRST;
+    for (let i = 0; i < size && port === null; i += 1) {
+      const candidate = WORKSPACE_PORT_FIRST + ((start + i) % size);
+      const other = read.claims.find((c) => c.port === candidate && c.taskId !== taskId);
+      if (other && isAlive(other.pid)) continue;
+      const held = listening(candidate);
+      if (held === null) return couldNotCheck(candidate);
+      if (held.length) continue;
+      if (other) dropped.add(other.taskId);
+      port = candidate;
+    }
+    if (port === null) return { state: 'exhausted', file };
+  }
+
+  const claims = read.claims.filter((c) => c.taskId !== taskId && !dropped.has(c.taskId));
+  claims.push({ taskId, port, path: workspace, pid, at: now.toISOString() });
+  const failed = writeClaims(file, claims);
+  return failed ? { state: 'failed', file, reason: failed } : { state, port, file };
+}
+
+/** Write-then-rename: a crash mid-write must not leave a truncated file that reads as "nothing allocated". */
+function writeClaims(file, claims) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = file + '.' + process.pid + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify({ claims }, null, 2) + '\n');
+    fs.renameSync(tmp, file);
+    return null;
+  } catch (e) {
+    return e.message;
+  }
+}
+
+/** Gives a task's port back. A ports file that cannot be trusted is left as it is. */
+export function releasePort(taskId, { env = process.env } = {}) {
+  const file = portsFile(env);
+  const read = readClaims(file);
+  if (read.refused) return { state: 'refused', file, reason: read.refused };
+  const claims = read.claims.filter((c) => c.taskId !== taskId);
+  if (claims.length === read.claims.length) return { state: 'none', file };
+  const failed = writeClaims(file, claims);
+  return failed ? { state: 'failed', file, reason: failed } : { state: 'released', file };
+}
+
+/** The environment a workspace's servers get: one new name, and the one the board already honours. */
+export function workspaceEnv(port) {
+  return { GREAT_CTO_WORKSPACE_PORT: String(port), BOARD_PORT: String(port) };
+}

package/board/scripts/lib/worktree-state.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * worktree-state — is there work sitting in a worktree that nobody landed?
+ *
+ * Why this exists
+ * ---------------
+ * On 2026-08-07 senior-dev implemented a library in a git worktree: 381 lines
+ * plus 394 lines of tests, thirty passing. Its verdict went to the worktree's
+ * own `.great_cto/` too, so the main tree saw an empty log and the pipeline
+ * read "no verdict recorded". The work was found because a `cp` happened to say
+ * "files are identical" — luck, not a mechanism. Worktrees are removed when the
+ * agent is done with them.
+ *
+ * Nothing anywhere notices. The main tree looks clean, which reads as "the agent
+ * produced nothing" rather than "the agent produced something you cannot see",
+ * and those are the same picture from the pipeline's side.
+ *
+ * This reports; it does not block. A worktree with changes is the normal state
+ * while an agent is working, and several may be live at once during a parallel
+ * fan-out. The failure is silence at the moment one stops, not the existence of
+ * uncommitted work.
+ */
+
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/** Where Claude Code puts agent worktrees, relative to the repo root. */
+export const WORKTREE_DIR = join('.claude', 'worktrees');
+
+/** Where one named worktree lives. The single reading of this path (ADR-047). */
+export function worktreePath(root, name = '') {
+  return join(root, WORKTREE_DIR, name);
+}
+
+/** Changes in one worktree, or null when it is clean or unreadable. */
+export function worktreeChanges(dir, { exec = execFileSync } = {}) {
+  let out;
+  try {
+    out = exec('git', ['-C', dir, 'status', '--porcelain'],
+      { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    // Not a git worktree, or git refused. A directory we cannot ask about is not
+    // evidence of work — say nothing rather than guess.
+    return null;
+  }
+  const lines = String(out).split('\n').map((l) => l.trim()).filter(Boolean);
+  return lines.length ? lines : null;
+}
+
+/** The branch work lands on, as a full ref, or null when none can be named. */
+export function integrationRef(git) {
+  const head = git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+  if (head) return head;
+  for (const ref of ['refs/remotes/origin/main', 'refs/remotes/origin/master', 'refs/heads/main', 'refs/heads/master']) {
+    if (git(['rev-parse', '--verify', '--quiet', ref])) return ref;
+  }
+  return null;
+}
+
+/**
+ * Commits in a worktree that the integration branch does not have, as
+ * { count, ref }, or null when there are none or git cannot say. A clean status
+ * proves nothing here: committed work leaves `git status` empty.
+ */
+export function unmergedCommits(dir, { exec = execFileSync } = {}) {
+  const opts = { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] };
+  const git = (args) => {
+    try { return String(exec('git', ['-C', dir, ...args], opts)).trim(); } catch { return ''; }
+  };
+  const ref = integrationRef(git);
+  if (!ref) return null;
+  try {
+    exec('git', ['-C', dir, 'merge-base', '--is-ancestor', 'HEAD', ref], opts);
+    return null; // landed
+  } catch (e) {
+    // Exit 1 is the answer "not an ancestor"; anything else is git failing to answer.
+    if (e.status !== 1) return null;
+  }
+  const count = Number(git(['rev-list', '--count', `${ref}..HEAD`]));
+  return count > 0 ? { count, ref: ref.replace(/^refs\/(remotes\/|heads\/)/, '') } : null;
+}
+
+/**
+ * Worktrees holding unlanded changes: uncommitted, or committed and not merged.
+ *
+ * `maxAgeMs` bounds it to worktrees touched recently: an abandoned one from last
+ * week is a cleanup task, not a stage that just stopped, and reporting it on
+ * every subagent stop would train people to ignore the message.
+ */
+export function worktreesWithChanges(root = process.cwd(), { maxAgeMs = 6 * 60 * 60 * 1000, now = Date.now(), exec } = {}) {
+  const base = worktreePath(root);
+  if (!existsSync(base)) return [];
+  let names;
+  try { names = readdirSync(base); } catch { return []; }
+
+  const out = [];
+  for (const name of names) {
+    const dir = join(base, name);
+    let mtime;
+    try {
+      const st = statSync(dir);
+      if (!st.isDirectory()) continue;
+      mtime = st.mtimeMs;
+    } catch { continue; }
+    if (now - mtime > maxAgeMs) continue;
+    const changes = worktreeChanges(dir, { exec });
+    const unmerged = unmergedCommits(dir, { exec });
+    if (changes || unmerged) out.push({ name, dir, changes: changes || [], unmerged, ageMs: now - mtime });
+  }
+  return out.sort((a, b) => a.ageMs - b.ageMs);
+}
+
+/** One operator-facing line, or null when there is nothing unlanded. */
+export function explainWorktrees(list) {
+  if (!list || !list.length) return null;
+  const parts = list.map((w) => {
+    const shown = w.changes.slice(0, 5).map((c) => c.replace(/^\S+\s+/, ''));
+    const more = w.changes.length > shown.length ? ` (+${w.changes.length - shown.length} more)` : '';
+    const held = [];
+    if (shown.length) held.push(`${shown.join(', ')}${more}`);
+    if (w.unmerged) held.push(`${w.unmerged.count} commit${w.unmerged.count === 1 ? '' : 's'} not on ${w.unmerged.ref}`);
+    return `${w.dir}: ${held.join('; ')}`;
+  });
+  return `work is sitting in a worktree and has not been landed — ${parts.join(' | ')}. `
+    + 'The main tree looks clean, which reads as "the agent produced nothing" rather than '
+    + '"the agent produced something you cannot see". Land it or say why not; worktrees are removed when the agent is done with them.';
+}

package/board/shared/pipeline.toml

@@ -93,6 +93,35 @@ on = ["NO_BUILD"]
 gate = "gate:product"
 next = []
 
+# A UI feature reaches design-advisor from here. The default edge above goes to
+# pm, and nothing else named design-advisor: it ran only when the orchestrator
+# happened to read the routing table, so "after architect" was a sentence and not
+# an edge. The stage cannot sit on the default edge, because a backend feature
+# would then wait for a design that never starts. The architect knows which case
+# this is, so its verdict picks the branch. No depth skip here: a contract exists
+# to be planned against, so pm runs after it at any depth.
+[transitions.architect.APPROVED_UI]
+on = ["APPROVED_UI"]
+produces = ["arch"]
+gate = "gate:arch"
+next = ["design-advisor"]
+
+# Draft screens before the CTO decides WHAT. product-owner records this instead of
+# raising gate:product, and the gate moves to the end of the draft: a person
+# approving a product should see what they are approving. No gate on this edge is
+# deliberate. It removes no check, it only moves the same one a stage later.
+[transitions.product-owner.SCREENS_NEEDED]
+on = ["SCREENS_NEEDED"]
+produces = ["brief"]
+next = ["design-advisor"]
+
+[transitions.design-advisor.SCREENS_DRAFT]
+on = ["SCREENS_DRAFT"]
+# docs/design/SCREENS-{slug}.html — throwaway drafts of the main scenario
+produces = ["screens"]
+gate = "gate:product"
+next = ["architect"]
+
 [transitions.pm]
 on = ["PLAN_READY", "DONE"]
 # PLAN-{slug}.md, and one IMPL-BRIEF per senior-dev task (Step 7b).

package/dist/release-activation.mjs

@@ -200,6 +200,29 @@ function expectedCandidate(files) {
     const inventory = files.map(file => ({ path: file.path, size: file.bytes.length, sha256: hash(file.bytes), mode: file.mode })).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
     return hash(JSON.stringify(inventory));
 }
+/** What npm wrote against what was admitted: names the first difference, keeps no bytes. */
+function candidateDifference(files, packageRoot) {
+    const actual = new Map(packageSnapshot(packageRoot).files.map(file => [file.path, file]));
+    const differing = files.filter(file => { const found = actual.get(file.path); return !found || found.sha256 !== hash(file.bytes) || found.mode !== file.mode; });
+    const first = differing[0], found = first && actual.get(first.path);
+    return { differing: differing.length, unexpected: [...actual.keys()].filter(name => !files.some(file => file.path === name)).length, ...(first ? { path: first.path, expectedMode: first.mode.toString(8), actualMode: found ? found.mode.toString(8) : null, sameBytes: !!found && found.sha256 === hash(first.bytes) } : {}) };
+}
+/** The result of a failed step, bounded: the journal explains the rollback and stays small. */
+function stepFailure(step, result) {
+    return { step, status: result?.status ?? null, signal: result?.signal ?? null, error: result?.error?.code || result?.error?.message || null,
+        stdout: String(result?.stdout || '').slice(-500), stderr: String(result?.stderr || '').slice(-2000) };
+}
+/** npm applies the caller's umask to the files it unpacks, and the admitted inventory
+ * includes modes. A private umask must not turn identical bytes into a failed activation. */
+function withPackageUmask(action) {
+    const previous = process.umask(0o022);
+    try {
+        return action();
+    }
+    finally {
+        process.umask(previous);
+    }
+}
 function privateInstallationState(stateRoot, packageRoot, { recovering = false } = {}) {
     const root = canonicalDirectory(stateRoot, { create: true, privateMode: true });
     const installationId = hash(packageRoot), dir = path.join(root, installationId);
@@ -303,9 +326,13 @@ function validJournal(journal, installation, state) {
         fail('invalid-recovery-selection');
     return journal;
 }
-function rollback(installation, state, journal, context) {
+function rollback(installation, state, journal, context, reason = null, detail = null) {
     try {
         validJournal(journal, installation, state);
+        if (reason) {
+            journal.failure = reason;
+            journal.failureDetail = detail;
+        }
         const backup = path.join(state.dir, 'transactions', journal.transactionId, 'previous/package');
         const snapshot = packageSnapshot(backup);
         if (snapshot.digest !== journal.previous.packageDigest)
@@ -314,7 +341,7 @@ function rollback(installation, state, journal, context) {
         if (stateMatches(current, journal.previous)) {
             journal.state = 'ROLLED_BACK';
             writeRecord(state.journalPath, journal);
-            return outcome('ROLLED_BACK', context);
+            return outcome('ROLLED_BACK', context, reason || journal.failure);
         }
         if (!journal.written || !stateMatches(current, journal.written))
             fail('recovery-target-drift-or-unobserved-write');
@@ -358,7 +385,7 @@ function rollback(installation, state, journal, context) {
         journal.state = 'ROLLED_BACK';
         journal.recovery = 'RESTORED_PREEXISTING_OPERATOR_STATE';
         writeRecord(state.journalPath, journal);
-        return outcome('ROLLED_BACK', context);
+        return outcome('ROLLED_BACK', context, reason || journal.failure);
     }
     catch (error) {
         journal.state = 'RECOVERY_REQUIRED';
@@ -467,7 +494,7 @@ export function activateNpmRelease(admission, options) {
         if (finalArtifact.sha256 !== artifact.sha256 || hash(readRegular(activationArchive, { max: 128 * 1024 * 1024 })) !== artifact.sha256)
             fail('artifact-changed-at-activation');
         const args = ['install', '--global', activationArchive, '--ignore-scripts', '--offline', '--prefix', installation.prefix, '--package-lock=false', '--no-save', '--audit=false', '--fund=false'];
-        const result = run(npmPath, args, { cwd: tx, env, encoding: 'utf8', timeout: 180000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+        const result = withPackageUmask(() => run(npmPath, args, { cwd: tx, env, encoding: 'utf8', timeout: 180000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] }));
         try {
             journal.written = targetState(installation);
         }
@@ -476,15 +503,20 @@ export function activateNpmRelease(admission, options) {
         }
         phase('ACTIVE');
         if (result?.error || result?.signal || result?.status !== 0)
-            return rollback(installation, state, journal, context);
-        if (!journal.written || journal.written.filesDigest !== expectedCandidate(payload.files))
-            return rollback(installation, state, journal, context);
+            return rollback(installation, state, journal, context, 'npm-install-failed', stepFailure('npm-install', result));
+        if (!journal.written)
+            return rollback(installation, state, journal, context, 'installed-package-unreadable');
+        if (journal.written.filesDigest !== expectedCandidate(payload.files))
+            return rollback(installation, state, journal, context, 'installed-files-differ-from-admitted', candidateDifference(payload.files, installation.packageRoot));
         if (!stateMatches(targetState(installation), journal.written))
             return outcome('RECOVERY_REQUIRED', context, 'target-drift-after-activation');
         for (const smokeArgs of [[installation.binaryPath, '--version'], [installation.binaryPath, 'codex-host', 'list']]) {
             const smoke = run(process.execPath, smokeArgs, { cwd: tx, env, encoding: 'utf8', timeout: 30000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
-            if (smoke?.error || smoke?.signal || smoke?.status !== 0 || (smokeArgs.includes('--version') && String(smoke.stdout || '').trim() !== info.version))
-                return rollback(installation, state, journal, context);
+            const step = 'smoke-' + (smokeArgs.includes('--version') ? 'version' : 'codex-host-list');
+            if (smoke?.error || smoke?.signal || smoke?.status !== 0)
+                return rollback(installation, state, journal, context, step + '-failed', stepFailure(step, smoke));
+            if (smokeArgs.includes('--version') && String(smoke.stdout || '').trim() !== info.version)
+                return rollback(installation, state, journal, context, 'smoke-version-mismatch', stepFailure(step, smoke));
             if (!stateMatches(targetState(installation), journal.written))
                 return outcome('RECOVERY_REQUIRED', context, 'target-drift-during-smoke');
         }
@@ -496,7 +528,7 @@ export function activateNpmRelease(admission, options) {
         if (journal && error.activationCrash)
             return outcome('RECOVERY_REQUIRED', context, 'interrupted-activation');
         if (journal && ['ACTIVATING', 'ACTIVE', 'RECOVERY_REQUIRED'].includes(journal.state)) {
-            return rollback(installation, state, journal, context);
+            return rollback(installation, state, journal, context, error.activationReason || 'activation-check-failed');
         }
         if (journal) {
             journal.state = 'REFUSED';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "3.75.9",
+  "version": "3.76.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",