@cluesmith/codev 3.3.2 → 3.3.4

package/dist/commands/consult/tree-tripwire.js

@@ -0,0 +1,356 @@
+/**
+ * Working-tree tripwire for consultation lanes (#1649).
+ *
+ * A reviewer is supposed to read the tree, never write to it. `consultant.md`
+ * now says so explicitly, but instruction is a probabilistic control: the claude
+ * lane runs with `permissionMode: 'bypassPermissions'`, so `Edit`/`Write`/`Bash`
+ * remain *reachable* even though nothing asks for them. In #1649 a review lane
+ * reverted three guards in a builder's worktree to check whether the tests were
+ * vacuous, and the only reason anyone found out is that the builder happened to
+ * diff against HEAD afterwards.
+ *
+ * This module is the detection half. It snapshots the tree before a lane runs
+ * and again after, and reports what moved. It does not block anything — its job
+ * is to turn a silent mutation into a loud one.
+ *
+ * ## Why not just diff `git status --porcelain` output
+ *
+ * Because the interesting case is a tree that was *already dirty*. A builder
+ * mid-phase has uncommitted work; porcelain reports ` M src/foo.ts` before the
+ * review and ` M src/foo.ts` after it, identical strings, while the file's
+ * contents changed underneath. So the snapshot pairs each path porcelain
+ * reports with a hash of its contents on disk.
+ *
+ * ## What it cannot see
+ *
+ * Files git ignores. That is deliberate — `.consult/` and `codev/projects/​*​/*.txt`
+ * are ignored, which is exactly why consult's own review output does not trip
+ * its own wire — but it does mean a lane writing into an ignored path goes
+ * unnoticed. Naming the tree under review is the goal here, not sandboxing.
+ *
+ * Edits *inside* a submodule, for the same reason: `git status` reports the
+ * submodule as one directory entry, so a changed file within it moves nothing
+ * this module can see.
+ *
+ * And an edit the lane restores byte-for-byte, which by construction leaves a
+ * before/after comparison nothing to compare. `consultant.md` is the only
+ * control for that case; there is a test asserting this silence, so the limit is
+ * pinned rather than assumed.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+const NO_IDENTITY = { head: null, branch: null };
+const UNAVAILABLE = (reason) => ({
+    available: false,
+    reason,
+    entries: new Map(),
+    identity: NO_IDENTITY,
+});
+/**
+ * Read HEAD and the branch name in one `git rev-parse`.
+ *
+ * Failure is not fatal to the snapshot. A freshly `git init`ed repository has no
+ * HEAD to resolve, and the file-level half of the tripwire works there perfectly
+ * well; refusing to watch the tree because the repo has no commits would trade a
+ * real check for a missing one.
+ */
+function readIdentity(workspaceRoot) {
+    try {
+        const raw = execFileSync('git', ['rev-parse', 'HEAD', '--abbrev-ref', 'HEAD'], {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (typeof raw !== 'string')
+            return NO_IDENTITY;
+        const [head, branch] = raw.trim().split('\n');
+        return { head: head || null, branch: branch || null };
+    }
+    catch {
+        return NO_IDENTITY;
+    }
+}
+/**
+ * Hash a working-tree file, or mark it absent.
+ *
+ * Absent is a real state, not an error: a path can appear in porcelain output
+ * as a staged deletion, and a lane that *deletes* a file is precisely what we
+ * are watching for.
+ */
+function hashPath(absolute) {
+    try {
+        const stat = fs.lstatSync(absolute);
+        if (!stat.isFile())
+            return `<${stat.isDirectory() ? 'dir' : 'special'}>`;
+        return crypto.createHash('sha256').update(fs.readFileSync(absolute)).digest('hex');
+    }
+    catch {
+        return '<absent>';
+    }
+}
+/**
+ * Snapshot the working tree of `workspaceRoot`.
+ *
+ * `-z` (NUL-separated) rather than plain `--porcelain` because git C-quotes
+ * paths containing spaces or non-ASCII in the human-readable form, and a quoted
+ * path cannot be handed back to `fs.readFileSync`. `--untracked-files=all` so
+ * a newly created file is listed individually instead of being collapsed into
+ * a single `?? dir/` entry.
+ *
+ * Records HEAD and the branch alongside the paths, so a lane that commits or
+ * switches refs is caught even when no file ends up looking different.
+ */
+export function snapshotTree(workspaceRoot) {
+    // Typed `unknown` rather than `string` so the guard below is a real check and
+    // not a comparison TypeScript has already narrowed away.
+    let raw;
+    try {
+        raw = execFileSync('git', ['status', '--porcelain', '-z', '--untracked-files=all'], {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+            maxBuffer: 32 * 1024 * 1024,
+            // Capture git's stderr instead of inheriting it. Otherwise a workspace
+            // that is not a repository prints a bare `fatal: not a git repository`
+            // over the top of the message we actually mean to show.
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        return UNAVAILABLE(err instanceof Error ? err.message.split('\n')[0] : String(err));
+    }
+    // The tripwire is a diagnostic wrapped around every lane, so it must never be
+    // the thing that breaks a consultation. If `git status` came back as anything
+    // other than text — a stubbed `execFileSync` under a test, a Buffer if the
+    // encoding option is ever dropped — report the snapshot as unavailable rather
+    // than throwing out of the wrapper and taking the review down with it.
+    if (typeof raw !== 'string') {
+        return UNAVAILABLE(`git status returned ${typeof raw}, not text`);
+    }
+    const entries = new Map();
+    // Each record is `XY <path>`; rename/copy records are followed by a second
+    // NUL-terminated field holding the ORIGINAL path, which must be consumed so
+    // it is not mistaken for the next record's status code.
+    const fields = raw.split('\0').filter((f) => f.length > 0);
+    for (let i = 0; i < fields.length; i++) {
+        const field = fields[i];
+        const status = field.slice(0, 2);
+        const rel = field.slice(3);
+        if (!rel)
+            continue;
+        entries.set(rel, `${status}:${hashPath(path.join(workspaceRoot, rel))}`);
+        if (status[0] === 'R' || status[0] === 'C') {
+            const origin = fields[++i];
+            if (origin !== undefined) {
+                entries.set(origin, `${status}-from:${hashPath(path.join(workspaceRoot, origin))}`);
+            }
+        }
+    }
+    return { available: true, entries, identity: readIdentity(workspaceRoot) };
+}
+/**
+ * Paths `consult` writes itself on every run, and which therefore are not
+ * evidence of anything.
+ *
+ * `.consult/history.log` is appended by `logQuery()` after the lane returns, so
+ * it lands inside the window this module measures. In this repo `.consult/` is
+ * gitignored and never surfaces — which is exactly why it was not obvious. A
+ * live run against a scratch repo without that entry reported the log file as a
+ * mutation on the very first try. An adopter's `.gitignore` is not something to
+ * depend on for correctness here.
+ */
+const CONSULT_OWNED_PREFIXES = ['.consult/'];
+/**
+ * Review files written by consultation lanes, which are not evidence either.
+ *
+ * `computePersistentOutputPath()` here and `getReviewFilePath()` in porch share
+ * one naming convention — `<project>/<id>-<phase>-iter<N>-<lane>.txt` under
+ * `codev/projects/` — and porch's verify step runs all three lanes in parallel
+ * against the same worktree. Each lane can only exclude its *own* output path,
+ * so without this every cmap round would have each lane reporting its two
+ * siblings' review files as mutations.
+ *
+ * Invisible in this repo, again, because `.gitignore` here carries
+ * `codev/projects/*​/*.txt` — but `CODEV_GITIGNORE_ENTRIES` does not ship that
+ * rule, so every adopter would have got a red banner on every cmap round. Same
+ * shape as the `.consult/history.log` false positive, and the reason this is a
+ * rule in code rather than a line in someone's `.gitignore`.
+ */
+const LANE_REVIEW_FILE = /^codev\/projects\/[^/]+\/[^/]+-iter\d+-[^/]+\.txt$/;
+/**
+ * Resolve a lane's `--output` to a repo-relative path, or null if it lands
+ * outside the workspace.
+ *
+ * `--output` arrives exactly as the user typed it, which may be relative
+ * (`consult -o review.txt`), so a raw `startsWith(workspaceRoot)` test misses it
+ * and the lane ends up reporting its own review file. Resolving first also kills
+ * the opposite error: a plain prefix test counts `/repo-2/x` as living inside
+ * `/repo`.
+ *
+ * The resolution base is **`cwd`, not `workspaceRoot`**, because that is where
+ * the file actually lands: every lane writes with a bare
+ * `fs.writeFileSync(outputPath, …)`, and `consult` never chdirs. Resolving
+ * against the workspace root instead would agree with reality only when the two
+ * happen to coincide — run `consult -o review.txt` from a subdirectory and the
+ * file is written to `<subdir>/review.txt` while the exclusion names
+ * `review.txt`, so the lane reports its own output as a mutation.
+ */
+export function relativeOutputPath(workspaceRoot, outputPath, cwd = process.cwd()) {
+    if (!outputPath)
+        return null;
+    const rel = path.relative(workspaceRoot, path.resolve(cwd, outputPath));
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    // Snapshot keys come from git, which always uses forward slashes.
+    return rel.split(path.sep).join('/');
+}
+/**
+ * Repo-relative paths that differ between two snapshots, sorted.
+ *
+ * `ignore` takes the extra paths this particular run owns — the lane's review
+ * output file, whose location depends on the project and phase. A tripwire that
+ * cries wolf about its own output would be trained away within a week.
+ */
+export function diffTreeSnapshots(before, after, ignore = []) {
+    if (!before.available || !after.available)
+        return [];
+    const ignored = new Set(ignore);
+    const isOurs = (rel) => ignored.has(rel) ||
+        CONSULT_OWNED_PREFIXES.some(prefix => rel.startsWith(prefix)) ||
+        LANE_REVIEW_FILE.test(rel);
+    const changed = new Set();
+    for (const [rel, sig] of after.entries) {
+        if (isOurs(rel))
+            continue;
+        if (before.entries.get(rel) !== sig)
+            changed.add(rel);
+    }
+    for (const rel of before.entries.keys()) {
+        if (isOurs(rel))
+            continue;
+        if (!after.entries.has(rel))
+            changed.add(rel);
+    }
+    return [...changed].sort();
+}
+/**
+ * Repository identity fields that differ between two snapshots.
+ *
+ * A field that was unreadable at either end is skipped rather than reported as
+ * a change: "we could not tell" and "it moved" are different claims, and only
+ * one of them is evidence.
+ */
+export function diffRepositoryIdentity(before, after) {
+    if (!before.available || !after.available)
+        return [];
+    const changes = [];
+    const fields = [
+        ['HEAD', 'head'],
+        ['branch', 'branch'],
+    ];
+    for (const [label, key] of fields) {
+        const a = before.identity[key];
+        const b = after.identity[key];
+        if (a === null || b === null)
+            continue;
+        if (a !== b)
+            changes.push({ field: label, before: a, after: b });
+    }
+    return changes;
+}
+/**
+ * Render a string safe to print to a terminal.
+ *
+ * Git path names are bytes, and almost anything that is not `/` or NUL is legal
+ * in one — including newlines and ESC. Printing such a name raw lets it forge
+ * the rest of the banner: a file called `\n  - harmless.ts` adds a line to the
+ * list, and one containing a CSI sequence can repaint or erase what is above it.
+ * The warning exists to be trusted, so nothing it prints gets to move the
+ * cursor. C0, DEL and C1 are escaped; ordinary Unicode is left alone.
+ */
+export function escapeControlChars(value) {
+    const named = {
+        '\n': '\\n',
+        '\r': '\\r',
+        '\t': '\\t',
+    };
+    // eslint-disable-next-line no-control-regex
+    return value.replace(/[\x00-\x1f\x7f-\x9f]/g, ch => named[ch] ?? `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`);
+}
+/**
+ * The warning for a repository that moved under the reviewer.
+ *
+ * Separate from the changed-files banner because it is a different fact with a
+ * different remedy: no file need look any different, and `git status` will not
+ * show you what happened — `git reflog` will.
+ */
+export function formatRepositoryMovedWarning(model, changes) {
+    return [
+        `REPOSITORY MOVED during the ${model} review (#1649).`,
+        'A consultant reviews the commit in front of it; it must never commit, or switch refs.',
+        ...changes.map(c => `  - ${c.field}: ${escapeControlChars(c.before)} -> ${escapeControlChars(c.after)}`),
+        'The files on disk may look untouched and still not be the ones this review describes.',
+        'Check `git reflog` and `git status` before trusting this review or shipping the branch.',
+    ].join('\n');
+}
+/** Cap the file list so a lane that touched hundreds of paths stays readable. */
+const MAX_LISTED = 20;
+/**
+ * The warning text, shared by the stderr banner and the review-output footer.
+ *
+ * Deliberately says the tree changed *while the lane ran*, not that the lane
+ * changed it. Under `cmap` all three lanes run as concurrent processes in one
+ * worktree, so each one sees the others' writes; asserting a culprit we cannot
+ * identify would be a claim the evidence does not support.
+ */
+export function formatTreeChangeWarning(model, files) {
+    const listed = files.slice(0, MAX_LISTED);
+    const rest = files.length - listed.length;
+    const lines = [
+        `WORKING TREE CHANGED during the ${model} review (#1649).`,
+        `A consultant reviews the tree; it must never write to it. ${files.length} path${files.length === 1 ? '' : 's'} changed while this lane was running:`,
+        ...listed.map(f => `  - ${escapeControlChars(f)}`),
+    ];
+    if (rest > 0)
+        lines.push(`  … and ${rest} more`);
+    lines.push('Check `git status` and `git diff` before trusting this review or shipping the branch.', 'Note: under cmap the lanes run concurrently in one worktree, so another lane — or you —', 'may be the writer. This warning names what moved, not who moved it.');
+    return lines.join('\n');
+}
+/**
+ * The warning for a post-review snapshot that could not be taken at all.
+ *
+ * Distinct from "the tree changed" because the failure is different in kind: we
+ * know something happened, and we cannot say what. Reported rather than
+ * swallowed — a comparison that silently returns "no changes" when it could not
+ * look is the failure mode this whole module exists to avoid.
+ */
+export function formatSnapshotLostWarning(model, reason) {
+    return [
+        `WORKING TREE UNREADABLE after the ${model} review (#1649).`,
+        'The tree was readable before this lane ran and `git status` fails now, so the tripwire',
+        'cannot say whether anything changed. This is not the same as "nothing changed".',
+        `Reason: ${escapeControlChars(reason ?? 'unknown')}`,
+        'Check `git status` and `git diff` before trusting this review or shipping the branch.',
+    ].join('\n');
+}
+/**
+ * Append the warning to a lane's review output so it survives into the file
+ * porch and the builder actually read — stderr scrolls past, review files don't.
+ *
+ * Written as a plain paragraph with no `VERDICT:` line, so `parseVerdict()`
+ * (which scans last→first for that prefix) still finds the reviewer's own
+ * verdict above it.
+ */
+export function appendTreeChangeWarningToOutput(outputPath, warning) {
+    if (!outputPath || !fs.existsSync(outputPath))
+        return;
+    try {
+        fs.appendFileSync(outputPath, `\n\n---\n\n## ⚠️ ${warning}\n`);
+    }
+    catch {
+        // The stderr banner already carried the warning; failing to annotate the
+        // file must not turn a successful review into a failed command.
+    }
+}
+//# sourceMappingURL=tree-tripwire.js.map

package/dist/commands/consult/tree-tripwire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-tripwire.js","sourceRoot":"","sources":["../../../src/commands/consult/tree-tripwire.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor.d.ts

@@ -31,6 +31,75 @@ export interface SessionLogCheck {
  * hermetic; this function is where the logic lives and is pinned by tests.
  */
 export declare function checkSessionLogs(logDir: string, env?: NodeJS.ProcessEnv): SessionLogCheck;
+export interface TowerEnvCheck {
+    status: 'ok' | 'warn' | 'skipped';
+    /** Claude Code session markers found on the running Tower daemon. */
+    markers: string[];
+    /** Running shellper daemons whose own env still carries markers. */
+    contaminatedSessions: number;
+    /** Human-readable one-liner. No colour codes. */
+    summary: string;
+    /** Present only when `status === 'warn'`. */
+    recommendation?: string;
+}
+/**
+ * Remediation for a Tower daemon that inherited the markers (#1219).
+ *
+ * A plain restart is enough for the *daemon*, but deliberately not for what it
+ * already spawned: `towerStop` leaves shellpers running on purpose
+ * (`commands/tower.ts` — they are detached so terminals survive a restart), so
+ * their agent processes keep the markers until each is restarted. Saying only
+ * "restart Tower" would be a half-truth that reads as a full fix.
+ */
+export declare const TOWER_ENV_RESTART_HINT: string;
+/**
+ * Remediation when Tower itself is clean but sessions it spawned earlier are not.
+ *
+ * The force-kill flag is named but not recommended outright: it ends every
+ * running agent on the machine, which is a bigger hammer than most cases need.
+ */
+export declare const TOWER_ENV_SESSION_HINT: string;
+/**
+ * Decide what the "Tower environment" doctor section should say (#1219).
+ *
+ * A Tower started from inside a Claude Code session inherits that session's
+ * markers and hands them to every agent it spawns, which turns transcript
+ * saving — and therefore resume — off for all of them. Newly started Towers
+ * scrub themselves, but a *long-running* daemon started before this fix (or by
+ * something other than `afx tower start`) can still be carrying them, and that
+ * is invisible until a crash-recovery attempt fails.
+ *
+ * The readers are injected so the decision is unit-testable without a live
+ * daemon; `doctor()` passes the real `ps eww` ones. A `null` Tower env means no
+ * Tower is running (or its env could not be read) — reported as `skipped`, never
+ * a warning, since "no Tower" is not a fault.
+ *
+ * `readSessionEnvs` covers what a daemon-only check would miss (CMAP review):
+ * shellpers are detached and survive `afx tower stop` by design, so after a
+ * plain restart Tower reads clean while the agents it spawned earlier are still
+ * carrying the markers — and still unresumable.
+ */
+export declare function checkTowerEnv(readTowerEnv: () => Record<string, string> | null, readSessionEnvs?: () => Array<Record<string, string>>): TowerEnvCheck;
+/**
+ * PIDs of the running shellper daemons — the processes that outlive Tower and
+ * so can still be carrying markers after Tower itself has been restarted clean.
+ */
+export declare function findShellperPids(): number[];
+/**
+ * Read a running process's environment via `ps eww`.
+ *
+ * `ps eww -o command=` prints the argv followed by the environment on one line,
+ * and `ps ww -o command=` prints the argv alone — so subtracting the second from
+ * the first leaves the environment with no argv tokens to misparse. Returns
+ * `null` when the process is gone or the two readings disagree (a race), rather
+ * than guessing. macOS has no `/proc`, so `ps` is the portable reader here.
+ *
+ * `ps` separates environment entries with spaces and does not quote them, so a
+ * *value* containing a space is truncated at that space. Names are unaffected,
+ * and this check only ever asks which variables are present — but that is why
+ * the result is not a general-purpose environment reader.
+ */
+export declare function readProcessEnv(pid: number): Record<string, string> | null;
 /**
  * Main doctor function
  */

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2DH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAyB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,CAgCjB;AA8gBD;;GAEG;AACH,wBAAsB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CAigB9C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8DH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAyB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,CAgCjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,qEAAqE;IACrE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAE6C,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAE2C,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EACjD,eAAe,GAAE,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAY,GAC9D,aAAa,CAwCf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAO3C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAoBzE;AAuhBD;;GAEG;AACH,wBAAsB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,CA4hB9C"}

package/dist/commands/doctor.js

@@ -19,6 +19,9 @@ import { findMigrationBackups, formatMigrationBackup, formatBytes, totalBytes, S
 import { resolveAgyBin, AGY_OAUTH_MARKERS } from './consult/index.js';
 import { checkCachedAgyAuth, recordAgyAuthState } from './consult/agy-auth-cache.js';
 import { AGENT_FARM_DIR } from '@cluesmith/codev-core/constants';
+import { findClaudeSessionMarkers } from '../lib/agent-env.js';
+import { getProcessesOnPort } from '../agent-farm/utils/port.js';
+import { DEFAULT_TOWER_PORT } from '@cluesmith/codev-sdk/constants';
 import { measureSessionLogs, resolveLogRetentionDays, formatBytes as formatLogBytes, } from '../agent-farm/servers/session-log-sweep.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -68,6 +71,133 @@ export function checkSessionLogs(logDir, env = process.env) {
             : 'restart Tower to run the retention sweep (afx tower stop && afx tower start)',
     };
 }
+/**
+ * Remediation for a Tower daemon that inherited the markers (#1219).
+ *
+ * A plain restart is enough for the *daemon*, but deliberately not for what it
+ * already spawned: `towerStop` leaves shellpers running on purpose
+ * (`commands/tower.ts` — they are detached so terminals survive a restart), so
+ * their agent processes keep the markers until each is restarted. Saying only
+ * "restart Tower" would be a half-truth that reads as a full fix.
+ */
+export const TOWER_ENV_RESTART_HINT = 'restart Tower (afx tower stop && afx tower start), then restart each affected agent — '
+    + 'a plain restart leaves existing shellper sessions running with the markers';
+/**
+ * Remediation when Tower itself is clean but sessions it spawned earlier are not.
+ *
+ * The force-kill flag is named but not recommended outright: it ends every
+ * running agent on the machine, which is a bigger hammer than most cases need.
+ */
+export const TOWER_ENV_SESSION_HINT = 'restart each affected agent to clear them (or, to end every running session at once, '
+    + 'afx tower stop --force-kill-all-child-processes — this kills all agents)';
+/**
+ * Decide what the "Tower environment" doctor section should say (#1219).
+ *
+ * A Tower started from inside a Claude Code session inherits that session's
+ * markers and hands them to every agent it spawns, which turns transcript
+ * saving — and therefore resume — off for all of them. Newly started Towers
+ * scrub themselves, but a *long-running* daemon started before this fix (or by
+ * something other than `afx tower start`) can still be carrying them, and that
+ * is invisible until a crash-recovery attempt fails.
+ *
+ * The readers are injected so the decision is unit-testable without a live
+ * daemon; `doctor()` passes the real `ps eww` ones. A `null` Tower env means no
+ * Tower is running (or its env could not be read) — reported as `skipped`, never
+ * a warning, since "no Tower" is not a fault.
+ *
+ * `readSessionEnvs` covers what a daemon-only check would miss (CMAP review):
+ * shellpers are detached and survive `afx tower stop` by design, so after a
+ * plain restart Tower reads clean while the agents it spawned earlier are still
+ * carrying the markers — and still unresumable.
+ */
+export function checkTowerEnv(readTowerEnv, readSessionEnvs = () => []) {
+    const env = readTowerEnv();
+    const markers = env ? findClaudeSessionMarkers(env) : [];
+    const contaminatedSessions = readSessionEnvs()
+        .filter((sessionEnv) => findClaudeSessionMarkers(sessionEnv).length > 0)
+        .length;
+    if (markers.length > 0) {
+        const sessionNote = contaminatedSessions > 0
+            ? `; ${contaminatedSessions} running session(s) already carry them`
+            : '';
+        return {
+            status: 'warn',
+            markers,
+            contaminatedSessions,
+            summary: `Tower inherited ${markers.length} Claude Code session marker(s): ${markers.join(', ')}${sessionNote}`,
+            recommendation: TOWER_ENV_RESTART_HINT,
+        };
+    }
+    // Sessions spawned before the restart are still contaminated — the case a
+    // daemon-only check would call "ok" while agents stay unresumable. Shellpers
+    // outlive Tower, so this holds whether or not a Tower is running now; only
+    // the wording changes, since "Tower is clean" is not true of an absent Tower.
+    if (contaminatedSessions > 0) {
+        const lead = env ? 'Tower is clean, but' : 'No Tower running, but';
+        return {
+            status: 'warn',
+            markers,
+            contaminatedSessions,
+            summary: `${lead} ${contaminatedSessions} running session(s) still carry Claude Code session markers`,
+            recommendation: TOWER_ENV_SESSION_HINT,
+        };
+    }
+    if (!env) {
+        return { status: 'skipped', markers: [], contaminatedSessions: 0, summary: 'Tower not running' };
+    }
+    return { status: 'ok', markers, contaminatedSessions, summary: 'Tower environment is clean' };
+}
+/**
+ * PIDs of the running shellper daemons — the processes that outlive Tower and
+ * so can still be carrying markers after Tower itself has been restarted clean.
+ */
+export function findShellperPids() {
+    const out = runCommand('pgrep', ['-f', 'shellper-main.js']);
+    if (!out)
+        return [];
+    return out
+        .split('\n')
+        .map((line) => parseInt(line.trim(), 10))
+        .filter((pid) => !isNaN(pid));
+}
+/**
+ * Read a running process's environment via `ps eww`.
+ *
+ * `ps eww -o command=` prints the argv followed by the environment on one line,
+ * and `ps ww -o command=` prints the argv alone — so subtracting the second from
+ * the first leaves the environment with no argv tokens to misparse. Returns
+ * `null` when the process is gone or the two readings disagree (a race), rather
+ * than guessing. macOS has no `/proc`, so `ps` is the portable reader here.
+ *
+ * `ps` separates environment entries with spaces and does not quote them, so a
+ * *value* containing a space is truncated at that space. Names are unaffected,
+ * and this check only ever asks which variables are present — but that is why
+ * the result is not a general-purpose environment reader.
+ */
+export function readProcessEnv(pid) {
+    // `ww` in both: without it `ps` truncates to the terminal width when stdout is
+    // a tty, and a truncated argv would break the prefix subtraction below.
+    const command = runCommand('ps', ['ww', '-o', 'command=', '-p', String(pid)]);
+    const withEnv = runCommand('ps', ['eww', '-o', 'command=', '-p', String(pid)]);
+    if (command === null || withEnv === null)
+        return null;
+    if (!withEnv.startsWith(command))
+        return null;
+    const env = {};
+    for (const token of withEnv.slice(command.length).trim().split(' ')) {
+        const eq = token.indexOf('=');
+        if (eq <= 0)
+            continue;
+        env[token.slice(0, eq)] = token.slice(eq + 1);
+    }
+    // No pairs parsed means `ps` showed us no environment at all — another user's
+    // process, or a platform where `e` is not honoured. Returning `{}` here would
+    // read downstream as "an environment with no markers", i.e. a clean bill of
+    // health for a process we never actually inspected. Say "unknown" instead.
+    if (Object.keys(env).length === 0)
+        return null;
+    return env;
+}
 /**
  * Compare semantic versions: returns true if v1 >= v2
  */
@@ -283,6 +413,14 @@ async function verifyClaudeViaSDK() {
         const session = claudeQuery({
             prompt: 'Reply OK',
             options: {
+                // The #1649 audit: this is the second `bypassPermissions` call site in the
+                // package, so it runs with the same unrestricted tool access the consult
+                // lane does. It is an auth probe, not a review — one turn, no tools needed
+                // — but it had nothing telling it so, and it runs in whatever directory the
+                // user typed `codev doctor` in. Say it outright, as consultant.md now does.
+                systemPrompt: 'You are a connectivity probe for `codev doctor`. Reply with the requested ' +
+                    'text and nothing else. Do not read, create, or modify any file, and do not ' +
+                    'run any command — there is no task here beyond answering.',
                 allowedTools: [],
                 maxTurns: 1,
                 permissionMode: 'bypassPermissions',
@@ -919,7 +1057,7 @@ export async function doctor() {
             }
             console.log('');
         }
-        // Full forge concept reporting: all 15 concepts with resolution source and executable check
+        // Full forge concept reporting: all 18 concepts with resolution source and executable check
         const forgeConfig = loadForgeConfig(workspaceRoot);
         const provider = forgeConfig?.provider ?? 'github';
         console.log(chalk.bold('Forge Concepts') + ` (provider: ${provider})`);
@@ -935,7 +1073,7 @@ export async function doctor() {
                 }
             }
         }
-        // Report all 15 concepts with source and executable availability
+        // Report all 18 concepts with source and executable availability
         const resolutions = resolveAllConcepts(forgeConfig);
         const missingExecs = new Set();
         for (const r of resolutions) {
@@ -1009,6 +1147,31 @@ export async function doctor() {
         console.log(`  ${chalk.green('✓')} ${sessionLogs.summary} ${chalk.blue(`(${sessionLogs.retentionNote})`)}`);
     }
     console.log('');
+    // Tower environment hygiene (#1219). A Tower that inherited a Claude Code
+    // session's markers spawns agents whose transcripts are never saved, so they
+    // cannot be resumed after a crash — silent until recovery time.
+    const towerPids = getProcessesOnPort(DEFAULT_TOWER_PORT);
+    const towerEnv = checkTowerEnv(() => (towerPids.length > 0 ? readProcessEnv(towerPids[0]) : null), () => findShellperPids()
+        .map(readProcessEnv)
+        .filter((e) => e !== null));
+    console.log(chalk.bold('Tower Environment') + ` (port ${DEFAULT_TOWER_PORT})`);
+    console.log('');
+    if (towerEnv.status === 'warn') {
+        console.log(`  ${chalk.yellow('⚠')} ${towerEnv.summary}`);
+        warnings++;
+        warningDetails.push({
+            name: 'Tower environment',
+            issue: towerEnv.summary,
+            recommendation: towerEnv.recommendation,
+        });
+    }
+    else if (towerEnv.status === 'skipped') {
+        console.log(`  ${chalk.blue('-')} ${towerEnv.summary}`);
+    }
+    else {
+        console.log(`  ${chalk.green('✓')} ${towerEnv.summary}`);
+    }
+    console.log('');
     // Summary
     console.log('============================================');
     if (errors > 0) {