peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/code-runtime-session.d.ts

@@ -0,0 +1 @@
+export declare function readActiveSid(projectRoot: string): string | null;

package/dist/cli/commands/code-runtime-session.js

@@ -0,0 +1,15 @@
+// The active-session probe the runtime commands share. It has a module of its own
+// because six registrars read it and none of them owns it.
+import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+export function readActiveSid(projectRoot) {
+    try {
+        const presence = getSkillPresence(projectRoot);
+        if (presence === null || presence === undefined)
+            return null;
+        return presence.sessionId ?? null;
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}

package/dist/cli/commands/codegraph-command-runtime.d.ts

@@ -1,4 +1,5 @@
 import { type CodegraphInvocationOptions } from '../../services/codegraph/codegraph-service.js';
+export { rewriteSqliteBackendAdvice } from '../../services/codegraph/codegraph-backend-advice.js';
 import { type ProgramIO } from '../cli-helpers.js';
 export interface CommonCodegraphOptions {
     project: string;
@@ -15,6 +16,11 @@ export declare function printCodegraphFailure(io: ProgramIO, command: string, er
  * untouched.
  */
 export declare function rewriteBareCodegraphHints(text: string): string;
+/**
+ * Both localizations upstream output needs before it reaches the reader, in
+ * the order the shipped pipeline applies them.
+ */
+export declare function localizeUpstreamCodegraphText(text: string): string;
 /**
  * Proxy one upstream invocation. Returns whether UPSTREAM FAILED — the
  * caller needs that to rank the exit-code precedence (an upstream failure

package/dist/cli/commands/codegraph-command-runtime.js

@@ -1,20 +1,25 @@
 // src/cli/commands/codegraph-command-runtime.ts
 //
 // Shared invocation runtime for every `peaks codegraph <verb>`: the option
-// shape they all extend, the failure envelope they all print, the hint
-// rewriter that keeps upstream's bare `codegraph …` hints runnable, and the
-// upstream proxy itself.
+// shape they all extend, the failure envelope they all print, the two text
+// localizations upstream output needs before it reaches the reader (bare
+// `codegraph …` hints, and the SQLite-backend advice for a dependency this
+// project removed), and the upstream proxy itself.
 //
 // Extracted verbatim from `codegraph-commands.ts` (rid
-// 2026-09-17-oversize-and-scale, D1 — the 800-line file-size cap). Every moved
 // line is byte-identical and no behaviour changed; `codegraph-commands.ts`
-// re-exports `rewriteBareCodegraphHints` so the public surface is stable.
+// re-exports the hint rewriter so its public surface is stable.
 //
 // This module is the BOTTOM of the codegraph CLI's import graph. It must not
 // import `codegraph-commands.ts` or `codegraph-status-command.ts`, or the
 // extraction would introduce a cycle.
+import { rewriteSqliteBackendAdvice } from '../../services/codegraph/codegraph-backend-advice.js';
 import { createCodegraphInvocation, executeCodegraphInvocation } from '../../services/codegraph/codegraph-service.js';
 import { fail } from 'peaks-loop-shared/result';
+// Re-exported so the CLI surface keeps serving the tests and callers that
+// import it from here; the implementation lives in the service layer because
+// the failure-note builders need the same matcher and may not import `src/cli`.
+export { rewriteSqliteBackendAdvice } from '../../services/codegraph/codegraph-backend-advice.js';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
 export function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
     printResult(io, fail(command, 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the codegraph command options and project path before retrying']), asJson);
@@ -32,6 +37,13 @@ export function printCodegraphFailure(io, command, error, asJson, exitCode = 1)
 export function rewriteBareCodegraphHints(text) {
     return text.replace(/(?<![\w-])(?<!peaks\s)codegraph(?=\s+(?:status|init|index|query|files|context|affected)\b)/g, 'peaks codegraph');
 }
+/**
+ * Both localizations upstream output needs before it reaches the reader, in
+ * the order the shipped pipeline applies them.
+ */
+export function localizeUpstreamCodegraphText(text) {
+    return rewriteSqliteBackendAdvice(rewriteBareCodegraphHints(text));
+}
 /**
  * Proxy one upstream invocation. Returns whether UPSTREAM FAILED — the
  * caller needs that to rank the exit-code precedence (an upstream failure
@@ -51,9 +63,9 @@ export async function runCodegraphCommand(io, command, options, asJson, attribut
             return true;
         }
         const didFail = result.exitCode !== null && result.exitCode !== 0;
-        const rewritten = rewriteBareCodegraphHints(result.stdout);
+        const rewritten = localizeUpstreamCodegraphText(result.stdout);
         const stdout = attributeStdout === undefined ? rewritten : attributeStdout(rewritten);
-        const stderr = rewriteBareCodegraphHints(result.stderr);
+        const stderr = localizeUpstreamCodegraphText(result.stderr);
         if (stdout.length > 0) {
             io.stdout((didFail ? redactSensitiveErrorMessage(stdout) : stdout).trimEnd());
         }

package/dist/cli/commands/codegraph-commands.js

@@ -4,19 +4,18 @@
 // `config-restore`, `init`, `affected`, plus the commander registration for
 // every codegraph subcommand.
 //
-// D1 (rid 2026-09-17-oversize-and-scale, the 800-line file-size cap) moved
 // the shared invocation runtime to `codegraph-command-runtime.ts` and the
 // `status` integrity gate to `codegraph-status-command.ts`, both verbatim.
 // This path keeps its public surface: `registerCodegraphCommands` is defined
 // here and `rewriteBareCodegraphHints` / `attributeUpstreamUpToDateLine` are
 // re-exported below, so every existing importer still resolves.
 import { InvalidArgumentError } from 'commander';
-import { statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { assertCodegraphDirContained, createCodegraphInvocation, executeCodegraphInvocation, defaultCodegraphInitGuard, resolveProjectRoot, writeCodegraphMarker, writeCodegraphAffectedContext, CodegraphInitConflictError, CODEGRAPH_DIR_NAME } from '../../services/codegraph/codegraph-service.js';
+import { resolve } from 'node:path';
+import { assertCodegraphDirContained, resolveProjectRoot, writeCodegraphAffectedContext } from '../../services/codegraph/codegraph-service.js';
 import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
-import { CODEGRAPH_CONFIG_FILENAME } from '../../services/codegraph/codegraph-exclude-reconciler.js';
+import { resolveCodegraphConfigSource } from '../../services/codegraph/codegraph-project-config.js';
 import { rollbackCodegraphConfig } from '../../services/codegraph/codegraph-config-repair-writer.js';
+import { runCodegraphInitCommand } from './codegraph-init-command.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
 import { printCodegraphFailure, runCodegraphCommand } from './codegraph-command-runtime.js';
@@ -40,31 +39,6 @@ function parsePositiveInteger(value) {
     }
     return parsed;
 }
-// " Include now admits 7 of 9 extractor-supported tracked file(s)." — printed
-// only when the ratio reports a SHORTFALL, i.e. when the repair has left
-// files the extractor supports unadmitted. That is the one reading of this
-// sentence an operator can act on.
-//
-// What this used to say, and why it was wrong: the denominator was fed from
-// the reconciler's admitted count — the NUMERATOR's own expression — so the
-// clause could only ever print "N of N", and it was gated on
-// `after > before` with a "(was N)" trailer computed by a second full glob
-// pass. A repo with 10 supported tracked files of which 5 were admitted was
-// told "5 of 5", asserting total coverage that nothing had measured. The
-// denominator is now an independent measurement (see the report field), and
-// the trailer — whose only consumer was this sentence — is gone with the
-// pass that produced it (perf: 11.73 ms of the repair entry's +14.13 ms, on
-// every automatic seam including no-ops).
-//
-// Silence when the ratio is complete is deliberate: "2 of 2" is true but
-// says nothing, and the patterns that changed are already named by the
-// caller's own sentence.
-function admittingClause(report) {
-    if (report.trackedSourceCount === 0 || report.includeAdmittedAfter >= report.trackedSourceCount) {
-        return '';
-    }
-    return ` Include now admits ${report.includeAdmittedAfter} of ${report.trackedSourceCount} extractor-supported tracked file(s).`;
-}
 const REPAIR_MODES = {
     exclude: {
         commandId: 'codegraph.repair-exclude',
@@ -80,32 +54,18 @@ const REPAIR_MODES = {
     }
 };
 // One sentence, the same shape in both modes, because both modes run the
-// same two-axis repair — only the rebuild differs.
+// same repair — only the rebuild differs.
 //
-// A1 (`2026-09-17-codegraph-msg-and-refresh`): EACH COUNT NAMES ITS OWN AXIS.
-// The previous wording ended one sentence about both axes with a single
-// "recovering N tracked source file(s)", fed by `filesRecovered` — the
-// EXCLUDE axis' counter. On this repo it printed "Added 5 include pattern(s)
-// and removed 0 exclude rule(s), recovering 0 tracked source file(s)." while
-// those 5 patterns had just admitted 31 tracked source files (30 `.mjs` + 1
-// `.cjs`): a true statement about the axis that did not move, read as a
-// verdict on the one that did. The `admittingClause` could not correct it
-// either — it is silent when the coverage ratio is complete, which is
-// exactly the state a fresh include repair produces.
-//
-// So: the include clause carries the include axis' own file delta and the
-// exclude clause carries the exclude axis' own count, and a reader cannot
-// attribute either number to the other clause. No combined total is printed,
-// because there is no honest single number here — the two axes recover
-// disjoint sets (one widens admission, the other unblocks admitted files)
-// and only the first of them is cheap enough to measure on every repair.
+// The include clause this sentence used to carry is gone with the include
+// axis (see `codegraph-exclude-repair.ts`), which also removed the reason the
+// sentence was once split in two: there is a single axis left, and its own
+// counter cannot be read as a verdict on another one.
 function appliedRepairNote(report) {
-    return (`Added ${report.includePatternsAdded.length} include pattern(s), newly admitting ${report.includeFilesRecovered} tracked source file(s), and removed ${report.rulesRemoved.length} exclude rule(s), recovering ${report.filesRecovered} tracked source file(s) that a rule had been hiding.` +
-        admittingClause(report) +
+    return (`Removed ${report.rulesRemoved.length} exclude rule(s), recovering ${report.filesRecovered} tracked source file(s) that a rule had been hiding.` +
         ` Config backed up to ${report.backupPath ?? ''}.`);
 }
 /**
- * Explicit repair path: reconcile both config axes → back up the config →
+ * Explicit repair path: reconcile the config's `exclude` rules → back it up →
  * rewrite it → rebuild the index. Mirrors the automatic step `init` runs
  * after a fresh upstream init, for workspaces that were already
  * initialized before the integrity gate existed.
@@ -141,11 +101,7 @@ async function runCodegraphRepairCommand(io, options, asJson, mode) {
     printResult(io, ok(spec.commandId, {
         applied: report.applied,
         rulesRemoved: report.rulesRemoved,
-        includePatternsAdded: report.includePatternsAdded,
         filesRecovered: report.filesRecovered,
-        includeFilesRecovered: report.includeFilesRecovered,
-        includeAdmittedAfter: report.includeAdmittedAfter,
-        trackedSourceCount: report.trackedSourceCount,
         configPath: report.configPath,
         backupPath: report.backupPath,
         reindexed: report.reindexed,
@@ -264,7 +220,9 @@ async function runCodegraphConfigRestoreCommand(io, options, asJson) {
         // into another. Called for its refusal only — the paths below stay derived
         // from the caller's canonical `projectRoot`.
         assertCodegraphDirContained(projectRoot);
-        configPath = join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_CONFIG_FILENAME);
+        // The same resolver the repair WRITES through, so a restore puts back the
+        // file the repair replaced — not a same-named file upstream never reads.
+        configPath = resolveCodegraphConfigSource(projectRoot).configPath;
     }
     catch (error) {
         // The PRECONDITION class: nothing below this line ran, so the envelope says
@@ -313,7 +271,6 @@ async function runCodegraphConfigRestoreCommand(io, options, asJson) {
     ]), asJson);
 }
 /**
- * rid-CG-006 — init conflict guard. Resolves the project root and
  * probes `.codegraph/` for the peaks-loop marker before invoking the
  * upstream binary.
  *
@@ -324,140 +281,7 @@ async function runCodegraphConfigRestoreCommand(io, options, asJson) {
  * On a successful upstream init, write the marker so the next run
  * hits the noop branch instead of the conflict branch.
  */
-async function runCodegraphInitCommand(io, options, asJson) {
-    let projectRoot;
-    try {
-        const candidate = resolve(options.project);
-        if (!statSync(candidate).isDirectory()) {
-            throw new Error('Project path must exist and be a directory');
-        }
-        projectRoot = candidate;
-    }
-    catch (error) {
-        printCodegraphFailure(io, 'codegraph.init', error, asJson);
-        return;
-    }
-    const guardOutcome = defaultCodegraphInitGuard(projectRoot);
-    if (guardOutcome.status === 'noop-already-peaks-loop') {
-        printResult(io, ok('codegraph.init', {
-            guard: guardOutcome.status,
-            codegraphDir: guardOutcome.codegraphDir,
-            markerPresent: true
-        }, 
-        // A no-op init is a SUCCESS. This message used to sit in the
-        // `warnings` slot and was therefore printed as
-        // `warning: .codegraph/ is already managed by peaks-loop...`.
-        [], [
-            `.codegraph/ is already managed by peaks-loop; init is a no-op. Marker: ${guardOutcome.codegraphDir}/.peaks-loop-marker`,
-            'Run `peaks codegraph index` to (re)build the index without touching the schema.'
-        ]), asJson);
-        return;
-    }
-    if (guardOutcome.status === 'conflict-foreign-schema') {
-        const conflict = new CodegraphInitConflictError(`Refusing to init: ${guardOutcome.codegraphDir} already exists with a non-peaks-loop schema. ` +
-            'Move or rename the foreign directory, then re-run `peaks codegraph init`.', guardOutcome.codegraphDir);
-        printResult(io, fail('codegraph.init', conflict.code, conflict.message, { codegraphDir: conflict.codegraphDir }, [
-            'Move or rename the foreign .codegraph/ directory before retrying.',
-            'Or remove .codegraph/ if you are sure no other tool owns it.',
-            'Or run `peaks codegraph init --project <path> --force` once the foreign-tool safety flag ships (tracked in rid-CG-006).'
-        ]), asJson);
-        process.exitCode = conflict.exitCode;
-        return;
-    }
-    // guardOutcome.status === 'fresh' — proceed.
-    try {
-        const invocation = createCodegraphInvocation({
-            subcommand: 'init',
-            project: options.project
-        });
-        const result = await executeCodegraphInvocation(invocation);
-        const didFail = result.exitCode !== null && result.exitCode !== 0;
-        if (result.stdout.length > 0) {
-            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
-        }
-        if (result.stderr.length > 0) {
-            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
-        }
-        if (didFail) {
-            if (asJson === true) {
-                printCodegraphFailure(io, 'codegraph.init', new Error(result.stderr || result.stdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode ?? 1);
-            }
-            process.exitCode = result.exitCode ?? 1;
-            return;
-        }
-        // Upstream succeeded — stamp the marker so the next run hits the
-        // noop branch. Best-effort: a marker-write failure must NOT undo
-        // the upstream init (peaks-loop still owns the schema logically).
-        try {
-            writeCodegraphMarker(guardOutcome.codegraphDir);
-        }
-        catch {
-            // intentionally swallowed — surface as warning below
-        }
-        // Upstream `init` writes BOTH default templates: a 99-rule `exclude`
-        // list (some rules collide with real source directories in this
-        // project) and a 32-entry `include` list (which omits five extensions
-        // upstream's own extractor supports). Left alone, a fresh clone / new
-        // machine gets an index that silently omits tracked source files while
-        // `status` says it is up to date. Reconcile now, append the missing
-        // include patterns, drop the offending rules, and rebuild the index — a
-        // fresh init is the one moment this is both safe (nothing has been
-        // indexed yet) and necessary (`.codegraph/` is gitignored, so every
-        // clone starts from the default templates).
-        //
-        // Never throws: a failure here is reported as a warning, not a
-        // failed init (the init itself already succeeded).
-        const configRepair = await repairCodegraphExcludeFromProject(projectRoot);
-        // These are confirmations, not warnings: `printResult` renders every
-        // `warnings` entry to stderr behind a `warning: ` prefix, so a fully
-        // successful init used to print a wall of `warning:` lines for what
-        // were plain success messages.
-        const initNotes = [
-            `Stamped peaks-loop marker at ${guardOutcome.codegraphDir}/.peaks-loop-marker`
-        ];
-        if (configRepair.applied) {
-            if (configRepair.includePatternsAdded.length > 0) {
-                // A1 (2026-09-17): the include axis names its OWN file delta here too.
-                // Naming the patterns alone left the same gap the repair note had —
-                // a reader learned which extensions were appended but not how many
-                // tracked files that admitted, and this note is the ONLY place a
-                // fresh `init` reports the include repair.
-                initNotes.push(`Added ${configRepair.includePatternsAdded.length} include pattern(s) upstream's extractor supports but its default template omits, newly admitting ${configRepair.includeFilesRecovered} tracked source file(s) (${configRepair.includePatternsAdded.join(', ')}).${admittingClause(configRepair)}`);
-            }
-            if (configRepair.rulesRemoved.length > 0) {
-                initNotes.push(`Removed ${configRepair.rulesRemoved.length} exclude rule(s) that blocked tracked source files, recovering ${configRepair.filesRecovered} file(s); config backed up to ${configRepair.backupPath ?? ''}.`);
-            }
-            if (configRepair.reindexed) {
-                initNotes.push('Rebuilt the codegraph index over the recovered files.');
-            }
-        }
-        printResult(io, ok('codegraph.init', {
-            guard: guardOutcome.status,
-            codegraphDir: guardOutcome.codegraphDir,
-            markerWritten: true,
-            excludeRepair: {
-                applied: configRepair.applied,
-                rulesRemoved: configRepair.rulesRemoved,
-                includePatternsAdded: configRepair.includePatternsAdded,
-                filesRecovered: configRepair.filesRecovered,
-                includeFilesRecovered: configRepair.includeFilesRecovered,
-                includeAdmittedAfter: configRepair.includeAdmittedAfter,
-                trackedSourceCount: configRepair.trackedSourceCount,
-                reindexed: configRepair.reindexed,
-                backupPath: configRepair.backupPath,
-                warning: configRepair.warning
-            }
-        }, 
-        // Verbatim: `printResult` supplies the `warning: ` prefix, so a
-        // prefix added here would render as `warning: warning: ...`.
-        configRepair.warning === null ? [] : [configRepair.warning], initNotes), asJson);
-    }
-    catch (error) {
-        printCodegraphFailure(io, 'codegraph.init', error, asJson);
-    }
-}
 /**
- * rid-CG-002 — codegraph-affected envelope write.
  *
  * Wraps the generic `runCodegraphCommand` and, after a successful
  * upstream invocation, calls `writeCodegraphAffectedContext` so the
@@ -531,14 +355,17 @@ export function registerCodegraphCommands(program, io) {
         .description('Show codegraph status, including the exclude integrity gate')).action((options) => runCodegraphStatusCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('repair-exclude')
-        .description('Normalize the codegraph include list, drop exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'exclude'));
+        .description('Drop config exclude rules that block tracked source files, then rebuild the index')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'exclude'));
     addProjectOption(codegraph
         .command('repair-index')
-        .description('Repair both codegraph config axes, then rebuild the index from scratch (drops rows for deleted files)')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'index'));
+        .description('Drop config exclude rules that block tracked source files, then rebuild the index from scratch (drops rows for deleted files)')).action((options) => runCodegraphRepairCommand(io, options, options.peaksJson, 'index'));
     addProjectOption(codegraph
         .command('config-restore')
         .description('Restore .codegraph/config.json from the byte-exact .bak a repair left — the explicit undo of a repair')).action((options) => runCodegraphConfigRestoreCommand(io, options, options.peaksJson));
-    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
+    addProjectOption(codegraph
+        .command('init')
+        .description('Initialize codegraph for a project')
+        .option('--force', 'delete a foreign (non-peaks-loop) .codegraph/ directory and initialize fresh; never follows a link and never deletes a peaks-loop-managed index')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('index')
         .description('Index a project with codegraph')

package/dist/cli/commands/codegraph-init-command.d.ts

@@ -0,0 +1,8 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type CommonCodegraphOptions } from './codegraph-command-runtime.js';
+/** `peaks codegraph init`'s own flags. Upstream `init` takes none. */
+export interface CodegraphInitOptions extends CommonCodegraphOptions {
+    force?: boolean;
+}
+declare function runCodegraphInitCommand(io: ProgramIO, options: CodegraphInitOptions, asJson?: boolean): Promise<void>;
+export { runCodegraphInitCommand };

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

@@ -0,0 +1,162 @@
+// src/cli/commands/codegraph-init-command.ts
+//
+// `peaks codegraph init` — the guarded init action.
+//
+// What it guarantees: it never reinitializes over a directory another tool
+// owns (`--force` is the only way past that, and it refuses a link and a
+// peaks-loop-marked directory); a successful init always stamps the peaks-loop
+// marker; the config's exclude rules are reconciled before the command
+// returns; and upstream's own output reaches the reader localized, the same
+// way every other codegraph verb does.
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createCodegraphInvocation, CodegraphInitConflictError, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker } from '../../services/codegraph/codegraph-service.js';
+import { repairCodegraphExcludeFromProject } from '../../services/codegraph/codegraph-exclude-repair.js';
+import { forcePastForeignConflict } from '../../services/codegraph/codegraph-foreign-removal.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { localizeUpstreamCodegraphText, printCodegraphFailure } from './codegraph-command-runtime.js';
+async function runCodegraphInitCommand(io, options, asJson) {
+    let projectRoot;
+    try {
+        const candidate = resolve(options.project);
+        if (!statSync(candidate).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
+        projectRoot = candidate;
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.init', error, asJson);
+        return;
+    }
+    let guardOutcome = defaultCodegraphInitGuard(projectRoot);
+    // `--force` replaces a FOREIGN `.codegraph/` (never a link, never our own
+    // marked index — codegraph-foreign-removal.ts). Re-running the guard after
+    // the removal means everything below sees an ordinary fresh init.
+    let foreignRemoved = null;
+    if (guardOutcome.status === 'conflict-foreign-schema' && options.force === true) {
+        try {
+            const forced = forcePastForeignConflict(projectRoot);
+            foreignRemoved = forced.removed;
+            guardOutcome = forced.outcome;
+        }
+        catch (error) {
+            printCodegraphFailure(io, 'codegraph.init', error, asJson);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (guardOutcome.status === 'noop-already-peaks-loop') {
+        printResult(io, ok('codegraph.init', {
+            guard: guardOutcome.status,
+            codegraphDir: guardOutcome.codegraphDir,
+            markerPresent: true
+        }, 
+        // A no-op init is a SUCCESS. This message used to sit in the
+        // `warnings` slot and was therefore printed as
+        // `warning: .codegraph/ is already managed by peaks-loop...`.
+        [], [
+            `.codegraph/ is already managed by peaks-loop; init is a no-op. Marker: ${guardOutcome.codegraphDir}/.peaks-loop-marker`,
+            'Run `peaks codegraph index` to (re)build the index without touching the schema.'
+        ]), asJson);
+        return;
+    }
+    if (guardOutcome.status === 'conflict-foreign-schema') {
+        const conflict = new CodegraphInitConflictError(`Refusing to init: ${guardOutcome.codegraphDir} already exists with a non-peaks-loop schema. ` +
+            'Move or rename the foreign directory, then re-run `peaks codegraph init`.', guardOutcome.codegraphDir);
+        printResult(io, fail('codegraph.init', conflict.code, conflict.message, { codegraphDir: conflict.codegraphDir }, [
+            'Move or rename the foreign .codegraph/ directory before retrying.',
+            'Or remove .codegraph/ if you are sure no other tool owns it.',
+            'Or run `peaks codegraph init --project <path> --force` to delete the foreign directory and initialize fresh (no backup; a link or a peaks-loop-marked directory is refused).'
+        ]), asJson);
+        process.exitCode = conflict.exitCode;
+        return;
+    }
+    // guardOutcome.status === 'fresh' — proceed.
+    try {
+        const invocation = createCodegraphInvocation({
+            subcommand: 'init',
+            project: options.project
+        });
+        const result = await executeCodegraphInvocation(invocation);
+        const didFail = result.exitCode !== null && result.exitCode !== 0;
+        // This path forwarded upstream
+        // verbatim, so the SQLite-backend advice for a dependency this project
+        // removed still reached the reader here.
+        const upstreamStdout = localizeUpstreamCodegraphText(result.stdout);
+        const upstreamStderr = localizeUpstreamCodegraphText(result.stderr);
+        if (upstreamStdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(upstreamStdout) : upstreamStdout).trimEnd());
+        }
+        if (upstreamStderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(upstreamStderr) : upstreamStderr).trimEnd());
+        }
+        if (didFail) {
+            if (asJson === true) {
+                printCodegraphFailure(io, 'codegraph.init', new Error(upstreamStderr || upstreamStdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode ?? 1);
+            }
+            process.exitCode = result.exitCode ?? 1;
+            return;
+        }
+        // Upstream succeeded — stamp the marker so the next run hits the
+        // noop branch. Best-effort: a marker-write failure must NOT undo
+        // the upstream init (peaks-loop still owns the schema logically).
+        try {
+            writeCodegraphMarker(guardOutcome.codegraphDir);
+        }
+        catch {
+            // intentionally swallowed — surface as warning below
+        }
+        // A project whose config excludes tracked source from its own index is
+        // left silently short by upstream `init`, while `status` reports the
+        // index up to date. Reconcile now, drop the offending rules, and rebuild
+        // the index — a fresh init is the one moment this is both safe (nothing
+        // has been indexed yet) and necessary (`.codegraph/` is gitignored, so
+        // every clone starts from whatever the project committed).
+        //
+        // Never throws: a failure here is reported as a warning, not a
+        // failed init (the init itself already succeeded).
+        const configRepair = await repairCodegraphExcludeFromProject(projectRoot);
+        // These are confirmations, not warnings: `printResult` renders every
+        // `warnings` entry to stderr behind a `warning: ` prefix, so a fully
+        // successful init used to print a wall of `warning:` lines for what
+        // were plain success messages.
+        const initNotes = [
+            `Stamped peaks-loop marker at ${guardOutcome.codegraphDir}/.peaks-loop-marker`
+        ];
+        if (foreignRemoved !== null) {
+            initNotes.push(`Removed the foreign ${foreignRemoved} (--force: deleted in place, no backup was kept), then initialized a fresh peaks-loop index.`);
+        }
+        if (configRepair.applied) {
+            if (configRepair.rulesRemoved.length > 0) {
+                initNotes.push(`Removed ${configRepair.rulesRemoved.length} exclude rule(s) that blocked tracked source files, recovering ${configRepair.filesRecovered} file(s); config backed up to ${configRepair.backupPath ?? ''}.`);
+            }
+            if (configRepair.reindexed) {
+                initNotes.push('Rebuilt the codegraph index over the recovered files.');
+            }
+        }
+        printResult(io, ok('codegraph.init', {
+            guard: guardOutcome.status,
+            codegraphDir: guardOutcome.codegraphDir,
+            ...(foreignRemoved === null
+                ? {}
+                : { foreignCodegraphRemoved: foreignRemoved, foreignCodegraphBackedUp: false }),
+            markerWritten: true,
+            excludeRepair: {
+                applied: configRepair.applied,
+                rulesRemoved: configRepair.rulesRemoved,
+                filesRecovered: configRepair.filesRecovered,
+                reindexed: configRepair.reindexed,
+                backupPath: configRepair.backupPath,
+                warning: configRepair.warning
+            }
+        }, 
+        // Verbatim: `printResult` supplies the `warning: ` prefix, so a
+        // prefix added here would render as `warning: warning: ...`.
+        configRepair.warning === null ? [] : [configRepair.warning], initNotes), asJson);
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.init', error, asJson);
+    }
+}
+export { runCodegraphInitCommand };

package/dist/cli/commands/codegraph-status-command.js

@@ -5,7 +5,6 @@
 // of upstream's `[OK] Index is up to date` line.
 //
 // Extracted verbatim from `codegraph-commands.ts` (rid
-// 2026-09-17-oversize-and-scale, D1 — the 800-line file-size cap). Every moved
 // line is byte-identical and no behaviour changed; `attributeUpstreamUpToDate
 // Line` stays importable from `codegraph-commands.ts`, which re-exports it.
 import { resolve } from 'node:path';
@@ -15,7 +14,7 @@ import { CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE, CODEGRAPH_INDEX_STRICT_ENV_VAR, CO
 import { readCodegraphProjectInputs } from '../../services/codegraph/codegraph-exclude-reconciler.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
-import { printCodegraphFailure, rewriteBareCodegraphHints, runCodegraphCommand } from './codegraph-command-runtime.js';
+import { localizeUpstreamCodegraphText, printCodegraphFailure, runCodegraphCommand } from './codegraph-command-runtime.js';
 const ANSI_SGR_PATTERN = /\x1b\[[0-9;]*m/g;
 /**
  * Upstream `status` answers a different question than peaks-loop's
@@ -96,8 +95,8 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
     }
     const upstream = {
         exitCode: result.exitCode,
-        stdout: rewriteBareCodegraphHints(result.stdout).trimEnd(),
-        stderr: redactSensitiveErrorMessage(rewriteBareCodegraphHints(result.stderr)).trimEnd()
+        stdout: localizeUpstreamCodegraphText(result.stdout).trimEnd(),
+        stderr: redactSensitiveErrorMessage(localizeUpstreamCodegraphText(result.stderr)).trimEnd()
     };
     const upstreamFailed = result.exitCode !== null && result.exitCode !== 0;
     const data = {
@@ -134,12 +133,12 @@ async function runCodegraphStatusJson(io, options, integrity, integrityWarning,
         printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_GAP', `codegraph index does not cover the repository: ${indexIntegrity?.includeGap.length ?? 0} extractor-supported tracked file(s) are not admitted by the config's include globs, and ${indexIntegrity?.deadRows.length ?? 0} index row(s) point at files that no longer exist.`, data, strict
             ? [
                 'The index must admit every extractor-supported tracked file and hold no row for a path that is gone.',
-                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to drop the blocking exclude rules and rebuild the index without the stale rows.`
             ]
             : [
                 'Advisory: this gap is reported as a warning and the command exits 0.',
                 `Set ${CODEGRAPH_INDEX_STRICT_ENV_VAR}=1 to make it blocking (exit ${CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE}).`,
-                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to add the missing include pattern(s) and rebuild the index without the stale rows.`
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to drop the blocking exclude rules and rebuild the index without the stale rows.`
             ]), true);
     }
     else {

package/dist/cli/commands/compact-command.d.ts

@@ -1,7 +1,6 @@
 /**
  * `peaks compact *` — strategic-compact CLI primitives.
  *
- * Slice 2026-07-01-strategic-compact-cli. Five subcommands under a new
  * top-level `peaks compact` group:
  *
  *   - suggest:    PreToolUse-style two-signal suggestion (context size
@@ -13,9 +12,13 @@
  *   - force:      Write a pre-compact checkpoint via
  *                 `peaks session checkpoint`; the IDE-side `/compact`
  *                 is still the LLM's call.
+ *   - history / harness-window / settle: the observability and hook
+ *                 transport for the window this group reports on.
  *
- * Each subcommand returns a `--json` envelope via `printResult`.
+ * Each subcommand returns a `--json` envelope via `printResult`. This module is
+ * the registrar: the parent group is created here and handed to each command's
+ * own module.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerCompactCommands(program: Command, io: ProgramIO): void;