peaks-loop 4.0.20 → 4.0.23

package/dist/cli/commands/sub-agent-shared.d.ts

@@ -48,6 +48,45 @@ export type DispatchOptions = {
     graphNode?: string;
     workflowId?: string;
     graphRef?: string;
+    /**
+     * rid-001 detached sub-agent dispatch (slice 2026-08-11): dispatch
+     * execution mode. `in-process` (default) keeps the existing warm-path
+     * CLI dispatch; `detached` shells out to
+     * `peaks-loop-internal-runtime/dispatch.dispatchDetached` for vendor
+     * CLI execution. Default `in-process` preserves backward compat with
+     * the 106+ existing dispatch call sites.
+     */
+    mode?: 'in-process' | 'detached';
+    /**
+     * rid-001 detached sub-agent dispatch: target vendor CLI when
+     * --mode detached is selected. Only consulted in the detached path;
+     * ignored in the default in-process path. Accepts `claude | codex
+     * | copilot` (matches VendorAdapterRegistry).
+     */
+    vendor?: 'claude' | 'codex' | 'copilot';
+    /**
+     * rid-001 Task 11.5 budget ceiling: user-overrides ResourceBudgetGuard
+     * when active concurrent fan-out would otherwise throttle detached
+     * dispatch. The user accepts the risk; surfaces as `warnings[]` only.
+     */
+    noThrottle?: boolean;
+    /**
+     * rid-001 Task 11.5: override the per-tenant max-concurrent budget
+     * (default 8). Effective in both detached (ResourceBudgetGuard) and
+     * in-process (batch-counter) paths.
+     */
+    maxConcurrent?: string;
+    /**
+     * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
+     * §Lesson 1): frontmatter `--must-ls-files <glob>` flag. When set, the
+     * dispatch CLI runs `git ls-files <glob>` upfront, surfaces
+     * `mustLsFilesVerification: { path, exists, files }` in the envelope,
+     * and prepends a `## must_ls_files enforcement` block to the sub-agent
+     * prompt so the LLM's first action MUST verify the file exists before
+     * claiming "PASS". Absent → unchanged behavior (backward compat with
+     * the 106+ existing dispatch call sites).
+     */
+    mustLsFiles?: string;
     json?: boolean;
 };
 export type HeartbeatOptions = {

package/dist/cli/commands/vendor-detect.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Phase B Task 20: peaks vendor-detect CLI.
+ * Reports which vendor CLIs are installed on PATH + recommends default.
+ * Spec: docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md §3.3
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
 export declare function vendorDetect(opts: {
     json: boolean;
 }): Promise<{
@@ -8,3 +15,11 @@ export declare function vendorDetect(opts: {
         recommended: string | null;
     };
 }>;
+/**
+ * `peaks vendor-detect` CLI registration (rid-001 redo).
+ * Slice 2026-08-11 detached-sub-agent-design §3.3 + §5.3 — register the
+ * previously-dead-coded `vendorDetect()` handler at the top-level program
+ * surface so `peaks vendor-detect --json` actually reaches it (was
+ * dead-coded at the CLI seam even though the handler existed).
+ */
+export declare function registerVendorDetectCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/vendor-detect.js

@@ -1,8 +1,5 @@
-/**
- * Phase B Task 20: peaks vendor-detect CLI.
- * Reports which vendor CLIs are installed on PATH + recommends default.
- * Spec: docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md §3.3
- */
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { ok } from 'peaks-loop-shared/result';
 import { defaultRegistry } from 'peaks-loop-internal-runtime';
 export async function vendorDetect(opts) {
     const reg = defaultRegistry();
@@ -14,3 +11,23 @@ export async function vendorDetect(opts) {
     const recommended = installed[0] ?? null;
     return { ok: true, command: 'vendor-detect', data: { installed, recommended } };
 }
+/**
+ * `peaks vendor-detect` CLI registration (rid-001 redo).
+ * Slice 2026-08-11 detached-sub-agent-design §3.3 + §5.3 — register the
+ * previously-dead-coded `vendorDetect()` handler at the top-level program
+ * surface so `peaks vendor-detect --json` actually reaches it (was
+ * dead-coded at the CLI seam even though the handler existed).
+ */
+export function registerVendorDetectCommand(program, io) {
+    addJsonOption(program
+        .command('vendor-detect')
+        .description('Detect which vendor CLIs (claude / codex / copilot) are installed ' +
+        'on PATH and recommend a default for --mode detached dispatch. ' +
+        'Returns `{ installed: string[], recommended: <id|null> }`.')).action(async (options) => {
+        const result = await vendorDetect({ json: options.json === true });
+        printResult(io, ok('vendor-detect', result.data, [], [
+            'Pass the recommended vendor id to `peaks sub-agent dispatch --mode detached --vendor <id>`.',
+            'Re-run with --json to machine-parse.'
+        ]), options.json === true);
+    });
+}

package/dist/cli/commands/workspace/init-command.js

@@ -26,6 +26,8 @@ import { resolveCanonicalProjectRoot } from '../../../services/config/config-ser
 import { applyHookInstall, readHookStatus } from '../../../services/skills/hooks-settings-service.js';
 import { clearStalePresenceOnRotation } from '../../../services/skills/skill-presence-service.js';
 import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
+import { defaultCodegraphInitGuard, writeCodegraphMarker } from '../../../services/codegraph/codegraph-service.js';
+import { mkdirSync } from 'node:fs';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 import { hasStandardsCheckedMarker, markStandardsChecked } from '../../../services/standards/missing-standards-detector.js';
@@ -337,6 +339,36 @@ export function registerWorkspaceInitCommand(workspace, io) {
             if (report.standardsMissing.missing) {
                 markStandardsChecked(projectRoot, sessionId);
             }
+            // rid-CG-001: auto-stake a peaks-loop-managed `.codegraph/`
+            // directory after a successful workspace init. Calls the
+            // conflict guard (rid-CG-006) BEFORE writing so a foreign
+            // schema is never silently overwritten. We deliberately do
+            // NOT spawn the upstream codegraph binary here — `peaks
+            // workspace init` must stay fast and offline-safe; the user
+            // runs `peaks codegraph index` next if they want the actual
+            // SQLite-backed index.
+            let codegraphAutoOutcome = null;
+            try {
+                const guard = defaultCodegraphInitGuard(projectRoot);
+                if (guard.status === 'fresh') {
+                    mkdirSync(guard.codegraphDir, { recursive: true });
+                    writeCodegraphMarker(guard.codegraphDir);
+                    codegraphAutoOutcome = { status: 'fresh' };
+                    nextActions.push(`Auto-created empty ${guard.codegraphDir}/ and stamped the peaks-loop marker. ` +
+                        'Run `peaks codegraph index --project <path>` next to build the SQLite-backed index.');
+                }
+                else if (guard.status === 'noop-already-peaks-loop') {
+                    codegraphAutoOutcome = { status: 'noop' };
+                }
+                else {
+                    codegraphAutoOutcome = { status: 'conflict' };
+                    warningsForEnvelope.push(`${guard.codegraphDir} already exists with a non-peaks-loop schema; ` +
+                        'refusing to auto-init codegraph. Run `peaks codegraph init --project <path>` after moving the foreign directory.');
+                }
+            }
+            catch (err) {
+                warningsForEnvelope.push(`codegraph auto-stake failed: ${getErrorMessage(err)}`);
+            }
             printResult(io, ok('workspace.init', {
                 ...report,
                 // Slice 018: surface outer-session-mismatch rotation in the
@@ -351,6 +383,8 @@ export function registerWorkspaceInitCommand(workspace, io) {
                     scope: hooksOutcome.scope,
                     ...(hooksOutcome.reason !== undefined ? { reason: hooksOutcome.reason } : {})
                 },
+                // rid-CG-001: surface codegraph auto-stake outcome.
+                ...(codegraphAutoOutcome !== null ? { codegraphAutoStake: codegraphAutoOutcome } : {}),
                 // Slice 2026-07-15-project-scan-bootstrap (G2): envelope
                 // for the .peaks/project-scan/ bootstrap. Always present
                 // (even when skipped / errored) so downstream readers can

package/dist/services/codegraph/codegraph-service.d.ts

@@ -40,4 +40,163 @@ export type CodegraphExecutionResult = {
 export type CodegraphProcessRunner = (invocation: CodegraphInvocation) => Promise<CodegraphExecutionResult>;
 export declare function createCodegraphInvocation(options: CodegraphInvocationOptions): CodegraphInvocation;
 export declare function executeCodegraphInvocation(invocation: CodegraphInvocation, runner?: CodegraphProcessRunner): Promise<CodegraphExecutionResult>;
+/**
+ * Slice rid-CG-006 — root `.codegraph/` (legacy). peaks-loop still
+ * reads from this location for back-compat with downstream consumers
+ * whose projects pre-date the slice rid-CG-003 preferred-path move.
+ */
+export declare const CODEGRAPH_DIR_NAME = ".codegraph";
+/**
+ * Slice rid-CG-003 — preferred managed location. Going forward
+ * peaks-loop writes here; legacy root `.codegraph/` is only used
+ * when it pre-exists AND `.peaks/.codegraph/` does not.
+ */
+export declare const PREFERRED_CODEGRAPH_DIR = ".peaks/.codegraph";
+/**
+ * Marker file peaks-loop writes inside the resolved codegraph dir
+ * after a successful upstream init. Its presence distinguishes
+ * peaks-loop-managed schemas from foreign ones (aider / cody /
+ * etc. all happily use the same directory name).
+ */
+export declare const CODEGRAPH_MARKER_NAME = ".peaks-loop-marker";
+export declare const CODEGRAPH_INIT_CONFLICT_EXIT_CODE = 73;
+export type ResolvedCodegraphLocation = {
+    readonly source: 'preferred';
+    readonly cwd: string;
+    readonly codegraphDir: string;
+} | {
+    readonly source: 'legacy';
+    readonly cwd: string;
+    readonly codegraphDir: string;
+} | {
+    readonly source: 'fresh-preferred';
+    readonly cwd: string;
+    readonly codegraphDir: string;
+};
+/**
+ * Slice rid-CG-003 — pure resolver that returns the cwd the
+ * upstream codegraph binary should be spawned with and the
+ * absolute path to the data directory it should read/write.
+ *
+ * Precedence:
+ *   1. `<projectRoot>/.peaks/.codegraph/` exists → use it
+ *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path)
+ *   2. `<projectRoot>/.codegraph/` exists → fall back to legacy
+ *      (cwd = `<projectRoot>`, codegraphDir = legacy path)
+ *   3. neither exists → default to the preferred path so the next
+ *      `peaks codegraph init` lands in `.peaks/.codegraph/`
+ *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path,
+ *       `source: 'fresh-preferred'`)
+ *
+ * The cwd is the directory the upstream binary treats as "project
+ * root" — the binary's default codegraph discovery reads
+ * `<cwd>/.codegraph/`, so we always set cwd to the PARENT of the
+ * resolved codegraph dir. Pure fs check; no IO beyond `existsSync`.
+ */
+export declare function resolveCodegraphProjectRoot(projectRoot: string): ResolvedCodegraphLocation;
+export type CodegraphInitGuardResult = {
+    status: 'fresh';
+    codegraphDir: string;
+} | {
+    status: 'noop-already-peaks-loop';
+    codegraphDir: string;
+} | {
+    status: 'conflict-foreign-schema';
+    codegraphDir: string;
+};
+export declare class CodegraphInitConflictError extends Error {
+    readonly codegraphDir: string;
+    readonly code = "CODEGRAPH_INIT_CONFLICT";
+    readonly exitCode = 73;
+    constructor(message: string, codegraphDir: string);
+}
+export type CodegraphInitGuard = (projectRoot: string) => CodegraphInitGuardResult;
+/**
+ * Slice rid-CG-003 — preferred-path-first init guard.
+ *
+ * Looks at `.peaks/.codegraph/` first; falls back to `.codegraph/`
+ * when the preferred path is absent. The 'fresh' case returns the
+ * preferred path so the next `peaks codegraph init` lands inside
+ * `.peaks/` instead of polluting the project root.
+ */
+export declare function defaultCodegraphInitGuard(projectRoot: string): CodegraphInitGuardResult;
+/**
+ * Pure-fs helper that stamps the peaks-loop marker AFTER a
+ * successful upstream init. The CLI action must call this after
+ * `executeCodegraphInvocation` returns exit 0.
+ */
+export declare function writeCodegraphMarker(codegraphDir: string): void;
+/**
+ * Test seam — pure stub of the default guard. Lets callers inject a
+ * pre-computed outcome without touching the real filesystem.
+ */
+export declare function constantCodegraphInitGuard(outcome: CodegraphInitGuardResult): CodegraphInitGuard;
+/**
+ * Per-file row rendered into the codegraph-context envelope's
+ * Markdown table. Symbol-count + cross-ref edges are intentionally
+ * optional: when the upstream `affected` JSON does not carry them
+ * (older codegraph versions, or a non-JSON stdout) we leave the
+ * cells blank instead of inventing numbers.
+ */
+export type CodegraphAffectedRow = {
+    readonly file: string;
+    readonly symbolCount?: number;
+    readonly crossRefEdges?: number;
+};
+export type WriteCodegraphAffectedContextInput = {
+    /** The peaks-loop project root (where `.peaks/_runtime/` lives). */
+    readonly projectRoot: string;
+    /** Request id, e.g. `rid-CG-002`. Used as the envelope's anchor. */
+    readonly rid: string;
+    /** Project-relative file paths passed to `peaks codegraph affected`. */
+    readonly files: readonly string[];
+    /** Raw upstream payload (string or already-parsed JSON). */
+    readonly affectedPayload: unknown;
+    /**
+     * Optional override for the active session id. When omitted,
+     * the writer calls `getSessionId(projectRoot)` and falls
+     * back to a graceful skip-with-warning when no binding is
+     * present (e.g. the consumer ran `peaks codegraph affected`
+     * outside of a peaks session).
+     */
+    readonly sessionId?: string | null;
+    /**
+     * Optional clock seam for tests; defaults to `new Date()`.
+     */
+    readonly now?: () => Date;
+};
+export type WriteCodegraphAffectedContextResult = {
+    readonly written: true;
+    readonly path: string;
+    readonly sessionId: string;
+} | {
+    readonly written: false;
+    readonly path: '';
+    readonly warning: string;
+};
+/**
+ * Pure renderer — turns the affected payload + rid + file list
+ * into a Markdown body with a leading human-readable table and
+ * a trailing JSON fence for machine consumers.
+ */
+export declare function renderCodegraphAffectedContext(rid: string, files: readonly string[], affectedPayload: unknown, sessionId: string, now?: () => Date): string;
+/**
+ * Write the `codegraph-context.md` envelope into the canonical
+ * session directory (`.peaks/_runtime/<sessionId>/rd/`). The
+ * envelope is what peaks-code's RD dispatch hook reads back to
+ * seed the QA / TXT handoff (see `peaks-code/SKILL.md`
+ * §"Codegraph orchestration context").
+ *
+ * The function is intentionally side-effect-safe:
+ *   - No session binding → returns `{ written: false, warning }`,
+ *     does NOT throw. Callers can either surface the warning or
+ *     treat it as a no-op.
+ *   - Directory creation is `mkdirSync({ recursive: true })`, so
+ *     the first run in a fresh session creates the `rd/` subdir
+ *     on demand.
+ *   - The path is canonicalized through `getSessionDir` so
+ *     downstream readers (QA / TXT) get a stable path even when
+ *     the caller passed a relative `projectRoot`.
+ */
+export declare function writeCodegraphAffectedContext(input: WriteCodegraphAffectedContextInput): WriteCodegraphAffectedContextResult;
 export {};

package/dist/services/codegraph/codegraph-service.js

@@ -1,7 +1,8 @@
-import { existsSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+import { getSessionId, getSessionDir } from '../session/index.js';
 const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
 const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
 const CODEGRAPH_EXECUTABLE = process.execPath;
@@ -142,6 +143,11 @@ function buildCommandArgs(options, projectRoot) {
 export function createCodegraphInvocation(options) {
     assertSupportedSubcommand(options.subcommand);
     const projectRoot = resolveProjectRoot(options.project);
+    // Slice rid-CG-003 — spawn the upstream binary inside the
+    // resolved codegraph dir's PARENT so its default `.codegraph/`
+    // discovery lands on `.peaks/.codegraph/` (preferred) or
+    // `.codegraph/` (legacy fallback).
+    const location = resolveCodegraphProjectRoot(projectRoot);
     assertSupportedOptions(options);
     assertRequiredOptions(options);
     assertPositiveInteger(options.limit, 'limit');
@@ -149,7 +155,7 @@ export function createCodegraphInvocation(options) {
     return {
         executable: CODEGRAPH_EXECUTABLE,
         args: buildCommandArgs(options, projectRoot),
-        cwd: projectRoot,
+        cwd: location.cwd,
         packageName: CODEGRAPH_PACKAGE_NAME,
         packageVersion: CODEGRAPH_PACKAGE_VERSION,
         subcommand: options.subcommand
@@ -158,3 +164,211 @@ export function createCodegraphInvocation(options) {
 export async function executeCodegraphInvocation(invocation, runner = defaultCodegraphProcessRunner) {
     return runner(invocation);
 }
+/* ──────────────────────────────────────────────────────────────────────
+ * Slice rid-CG-003 — preferred `.peaks/.codegraph/` lookup + legacy
+ * root `.codegraph/` fallback (spike follow-up #1).
+ * ────────────────────────────────────────────────────────────────────── */
+/**
+ * Slice rid-CG-006 — root `.codegraph/` (legacy). peaks-loop still
+ * reads from this location for back-compat with downstream consumers
+ * whose projects pre-date the slice rid-CG-003 preferred-path move.
+ */
+export const CODEGRAPH_DIR_NAME = '.codegraph';
+/**
+ * Slice rid-CG-003 — preferred managed location. Going forward
+ * peaks-loop writes here; legacy root `.codegraph/` is only used
+ * when it pre-exists AND `.peaks/.codegraph/` does not.
+ */
+export const PREFERRED_CODEGRAPH_DIR = '.peaks/.codegraph';
+/**
+ * Marker file peaks-loop writes inside the resolved codegraph dir
+ * after a successful upstream init. Its presence distinguishes
+ * peaks-loop-managed schemas from foreign ones (aider / cody /
+ * etc. all happily use the same directory name).
+ */
+export const CODEGRAPH_MARKER_NAME = '.peaks-loop-marker';
+export const CODEGRAPH_INIT_CONFLICT_EXIT_CODE = 73;
+/**
+ * Slice rid-CG-003 — pure resolver that returns the cwd the
+ * upstream codegraph binary should be spawned with and the
+ * absolute path to the data directory it should read/write.
+ *
+ * Precedence:
+ *   1. `<projectRoot>/.peaks/.codegraph/` exists → use it
+ *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path)
+ *   2. `<projectRoot>/.codegraph/` exists → fall back to legacy
+ *      (cwd = `<projectRoot>`, codegraphDir = legacy path)
+ *   3. neither exists → default to the preferred path so the next
+ *      `peaks codegraph init` lands in `.peaks/.codegraph/`
+ *      (cwd = `<projectRoot>/.peaks`, codegraphDir = preferred path,
+ *       `source: 'fresh-preferred'`)
+ *
+ * The cwd is the directory the upstream binary treats as "project
+ * root" — the binary's default codegraph discovery reads
+ * `<cwd>/.codegraph/`, so we always set cwd to the PARENT of the
+ * resolved codegraph dir. Pure fs check; no IO beyond `existsSync`.
+ */
+export function resolveCodegraphProjectRoot(projectRoot) {
+    const preferredDir = join(projectRoot, PREFERRED_CODEGRAPH_DIR);
+    const legacyDir = join(projectRoot, CODEGRAPH_DIR_NAME);
+    if (existsSync(preferredDir)) {
+        return {
+            source: 'preferred',
+            cwd: join(projectRoot, '.peaks'),
+            codegraphDir: preferredDir
+        };
+    }
+    if (existsSync(legacyDir)) {
+        return {
+            source: 'legacy',
+            cwd: projectRoot,
+            codegraphDir: legacyDir
+        };
+    }
+    return {
+        source: 'fresh-preferred',
+        cwd: join(projectRoot, '.peaks'),
+        codegraphDir: preferredDir
+    };
+}
+export class CodegraphInitConflictError extends Error {
+    codegraphDir;
+    code = 'CODEGRAPH_INIT_CONFLICT';
+    exitCode = CODEGRAPH_INIT_CONFLICT_EXIT_CODE;
+    constructor(message, codegraphDir) {
+        super(message);
+        this.codegraphDir = codegraphDir;
+        this.name = 'CodegraphInitConflictError';
+    }
+}
+/**
+ * Inspect a candidate codegraph directory and return its guard
+ * status. A file (or symlink-to-file) at the path counts as a
+ * foreign-schema conflict because it blocks directory creation.
+ */
+function inspectCandidateCodegraphDir(codegraphDir) {
+    let isDir = false;
+    try {
+        isDir = statSync(codegraphDir).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        return { status: 'conflict-foreign-schema', codegraphDir };
+    }
+    const markerPath = join(codegraphDir, CODEGRAPH_MARKER_NAME);
+    if (existsSync(markerPath)) {
+        return { status: 'noop-already-peaks-loop', codegraphDir };
+    }
+    return { status: 'conflict-foreign-schema', codegraphDir };
+}
+/**
+ * Slice rid-CG-003 — preferred-path-first init guard.
+ *
+ * Looks at `.peaks/.codegraph/` first; falls back to `.codegraph/`
+ * when the preferred path is absent. The 'fresh' case returns the
+ * preferred path so the next `peaks codegraph init` lands inside
+ * `.peaks/` instead of polluting the project root.
+ */
+export function defaultCodegraphInitGuard(projectRoot) {
+    const preferredDir = join(projectRoot, PREFERRED_CODEGRAPH_DIR);
+    const legacyDir = join(projectRoot, CODEGRAPH_DIR_NAME);
+    if (existsSync(preferredDir)) {
+        return inspectCandidateCodegraphDir(preferredDir);
+    }
+    if (existsSync(legacyDir)) {
+        return inspectCandidateCodegraphDir(legacyDir);
+    }
+    return { status: 'fresh', codegraphDir: preferredDir };
+}
+/**
+ * Pure-fs helper that stamps the peaks-loop marker AFTER a
+ * successful upstream init. The CLI action must call this after
+ * `executeCodegraphInvocation` returns exit 0.
+ */
+export function writeCodegraphMarker(codegraphDir) {
+    writeFileSync(join(codegraphDir, CODEGRAPH_MARKER_NAME), 'peaks-loop-managed\n', 'utf8');
+}
+/**
+ * Test seam — pure stub of the default guard. Lets callers inject a
+ * pre-computed outcome without touching the real filesystem.
+ */
+export function constantCodegraphInitGuard(outcome) {
+    return () => outcome;
+}
+/**
+ * Pure renderer — turns the affected payload + rid + file list
+ * into a Markdown body with a leading human-readable table and
+ * a trailing JSON fence for machine consumers.
+ */
+export function renderCodegraphAffectedContext(rid, files, affectedPayload, sessionId, now = () => new Date()) {
+    const rows = files.map((file) => ({ file }));
+    const generatedAt = now().toISOString();
+    const lines = [
+        '# Codegraph orchestration context',
+        '',
+        `- sessionId: \`${sessionId}\``,
+        `- rid: \`${rid}\``,
+        `- generatedAt: \`${generatedAt}\``,
+        '',
+        '## Affected files',
+        '',
+        '| file | symbolCount | crossRefEdges |',
+        '| --- | --- | --- |',
+        ...rows.map((row) => {
+            const sym = row.symbolCount === undefined ? '' : String(row.symbolCount);
+            const edges = row.crossRefEdges === undefined ? '' : String(row.crossRefEdges);
+            return `| \`${row.file}\` | ${sym} | ${edges} |`;
+        }),
+        '',
+        '## Raw upstream output',
+        '',
+        '```json',
+        typeof affectedPayload === 'string'
+            ? affectedPayload
+            : JSON.stringify(affectedPayload, null, 2),
+        '```',
+        ''
+    ];
+    return lines.join('\n');
+}
+/**
+ * Write the `codegraph-context.md` envelope into the canonical
+ * session directory (`.peaks/_runtime/<sessionId>/rd/`). The
+ * envelope is what peaks-code's RD dispatch hook reads back to
+ * seed the QA / TXT handoff (see `peaks-code/SKILL.md`
+ * §"Codegraph orchestration context").
+ *
+ * The function is intentionally side-effect-safe:
+ *   - No session binding → returns `{ written: false, warning }`,
+ *     does NOT throw. Callers can either surface the warning or
+ *     treat it as a no-op.
+ *   - Directory creation is `mkdirSync({ recursive: true })`, so
+ *     the first run in a fresh session creates the `rd/` subdir
+ *     on demand.
+ *   - The path is canonicalized through `getSessionDir` so
+ *     downstream readers (QA / TXT) get a stable path even when
+ *     the caller passed a relative `projectRoot`.
+ */
+export function writeCodegraphAffectedContext(input) {
+    const sessionId = input.sessionId ?? getSessionId(input.projectRoot);
+    if (!sessionId || sessionId.length === 0) {
+        return {
+            written: false,
+            path: '',
+            warning: 'No active peaks-loop session binding; skipping codegraph-context envelope. ' +
+                'Run `peaks workspace init` (or `peaks session set <id>`) and re-invoke ' +
+                '`peaks codegraph affected`.'
+        };
+    }
+    const sessionDir = getSessionDir(input.projectRoot, sessionId);
+    const rdDir = join(sessionDir, 'rd');
+    if (!existsSync(rdDir)) {
+        mkdirSync(rdDir, { recursive: true });
+    }
+    const contextPath = join(rdDir, 'codegraph-context.md');
+    const body = renderCodegraphAffectedContext(input.rid, input.files, input.affectedPayload, sessionId, input.now);
+    writeFileSync(contextPath, body, 'utf8');
+    return { written: true, path: contextPath, sessionId };
+}

package/dist/services/doctor/doctor-service/checks/codegraph-capability.d.ts

@@ -6,6 +6,13 @@
  * Fails when the version drifts, when the binary is missing, or
  * when the package is not resolvable at all.
  *
+ * Slice rid-CG-003 (spike follow-up #3): also detects which managed
+ * codegraph directory is in use — `.peaks/.codegraph/` (preferred)
+ * or root `.codegraph/` (legacy) — via the injected `managedPathProbe`.
+ * The CG-007 yarn-pnp fallback is preserved as the package-resolution
+ * default; the managed-path probe defaults to the same fs-walk-style
+ * helper and is independently injectable for tests.
+ *
  * The probe is injected so tests do not depend on the real
  * `node_modules` resolution; the default probe uses
  * `createRequire(import.meta.url)` to find the package.