@pugi/cli 0.1.0-beta.31 → 0.1.0-beta.35

package/dist/commands/smoke.js

@@ -0,0 +1,133 @@
+/**
+ * `pugi smoke` — runs the bundled scenario corpus through the headless
+ * harness and reports pass/fail per scenario (BIG TRACK 10 Phase 1,
+ * 2026-05-27).
+ *
+ * The CLI surface lives here rather than in `runtime/cli.ts` so the
+ * dispatch surface stays focused on argv routing. This module owns:
+ *
+ *   - Resolving the scenarios directory (default
+ *     `<cli-root>/test/scenarios/` when bundled, configurable via
+ *     `--scenarios-dir`).
+ *   - Selecting the `pugi` binary the headless driver should spawn.
+ *     Local development: `node <cli-root>/bin/run.js`. CI / published
+ *     usage: the `pugi` on PATH.
+ *   - Forwarding the orchestrator output to the unified
+ *     `writeOutput` writer so `--json` mode works without a second
+ *     code path.
+ *
+ * Phase 1 deliberately ships ONE flag (`--filter`) and one option
+ * (`--scenarios-dir`); the rest of the surface comes in Phase 2 once
+ * the engine path is wired and we know which scenarios actually need
+ * per-run plumbing (timeouts, fixture credentials, hermetic stubs).
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runSmoke, renderReportText, } from '../core/smoke/orchestrator.js';
+import { runHeadlessScenario } from '../core/smoke/headless-driver.js';
+/**
+ * Entry point invoked by `runtime/cli.ts::dispatchSmoke`. Returns the
+ * desired process exit code so the dispatcher can set
+ * `process.exitCode` without a second round-trip.
+ */
+export async function runSmokeCommand(ctx) {
+    // Parse the (small) command-local argv. We only honor flags this
+    // command actually consumes; unknown args produce a usage error so
+    // typos surface immediately.
+    let scenariosDirOverride = ctx.scenariosDir ?? undefined;
+    let filter = ctx.filter ?? '';
+    for (let i = 0; i < ctx.args.length; i += 1) {
+        const arg = ctx.args[i] ?? '';
+        if (arg === '--filter') {
+            const next = ctx.args[i + 1];
+            if (!next || next.startsWith('--')) {
+                ctx.writeOutput({ ok: false, error: '--filter requires a pattern' }, 'pugi smoke: --filter requires a pattern (substring or *-glob)');
+                return 2;
+            }
+            filter = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--filter=')) {
+            filter = arg.slice('--filter='.length);
+        }
+        else if (arg === '--scenarios-dir') {
+            const next = ctx.args[i + 1];
+            if (!next || next.startsWith('--')) {
+                ctx.writeOutput({ ok: false, error: '--scenarios-dir requires a path' }, 'pugi smoke: --scenarios-dir requires a path');
+                return 2;
+            }
+            scenariosDirOverride = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--scenarios-dir=')) {
+            scenariosDirOverride = arg.slice('--scenarios-dir='.length);
+        }
+        else if (arg === '--help' || arg === '-h') {
+            ctx.writeOutput({
+                ok: true,
+                usage: 'pugi smoke [--filter <pattern>] [--scenarios-dir <path>]',
+            }, [
+                'pugi smoke — run the bundled scenario corpus headlessly.',
+                '',
+                'Flags:',
+                '  --filter <pattern>     Run a subset (substring or *-glob match on scenario id).',
+                '  --scenarios-dir <path> Override the scenarios directory (default: bundled corpus).',
+            ].join('\n'));
+            return 0;
+        }
+        else {
+            ctx.writeOutput({ ok: false, error: `unknown arg: ${arg}` }, `pugi smoke: unknown arg ${arg}`);
+            return 2;
+        }
+    }
+    const scenariosDir = scenariosDirOverride ?? resolveBundledScenariosDir();
+    if (!existsSync(scenariosDir)) {
+        ctx.writeOutput({ ok: false, error: `scenarios dir not found: ${scenariosDir}` }, `pugi smoke: scenarios dir not found: ${scenariosDir}`);
+        return 2;
+    }
+    const pugiBin = ctx.pugiBin ?? process.env.PUGI_SMOKE_BIN ?? 'pugi';
+    const log = ctx.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const report = await runSmoke({
+        scenariosDir,
+        filter,
+        executor: (scenario) => runHeadlessScenario(scenario, { pugiBin }),
+        log,
+    });
+    if (ctx.json) {
+        ctx.writeOutput(report, renderReportText(report));
+    }
+    else {
+        process.stdout.write(`${renderReportText(report)}\n`);
+    }
+    return report.exitCode;
+}
+/**
+ * Resolve the scenarios directory that ships alongside the CLI.
+ *
+ * Both the dev source layout (`<cli-root>/src/commands/smoke.ts`) and
+ * the built output layout (`<cli-root>/dist/commands/smoke.js`) land
+ * on the same `../../test/scenarios` path relative to this file.
+ * The bundled `npm i -g @pugi/cli` install replicates that structure
+ * by shipping `test/scenarios` (glob `**\/*.scenario.txt`) via the
+ * `package.json` `files` field — so the single resolved path works in
+ * dev, in `tsx` runs, and in published installs without a config knob.
+ *
+ * If a future restructure ever bundles scenarios at
+ * `<cli-root>/dist/scenarios/` instead, add that to the fallback chain
+ * here AND mirror the path in `package.json` `files`. Until then we
+ * keep the resolver intentionally one-line.
+ */
+export function resolveBundledScenariosDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Works for both src/commands/smoke.ts and dist/commands/smoke.js —
+    // both live two directories below the cli root.
+    const bundled = resolve(here, '..', '..', 'test', 'scenarios');
+    if (existsSync(bundled))
+        return bundled;
+    // Last resort: return the expected path so the orchestrator surfaces
+    // a clean "scenarios dir not found" diagnostic at the call site
+    // rather than the resolver swallowing it silently.
+    return bundled;
+}
+//# sourceMappingURL=smoke.js.map

package/dist/core/auth/ensure-authenticated.js

@@ -0,0 +1,129 @@
+/**
+ * Wave 6 UX (2026-05-27) — `ensureAuthenticated` helper.
+ *
+ * Auto-login pre-flight for every Pugi command that needs an Anvil
+ * credential. Before this helper landed, cold-start without a stored
+ * credential surfaced a generic "Login required" message and the
+ * operator had к run `pugi login` separately, which broke the muscle-
+ * memory of "open terminal, type the command, see the answer".
+ *
+ * The helper exposes a single contract: `ensureAuthenticated(opts)`.
+ * On a happy path (credential resolves) it returns the credential.
+ * On a cold-start it either:
+ *
+ *   - launches the device-flow login inline (interactive TTY only,
+ *     `--no-login` not set), waits for completion, then re-resolves
+ *     the credential and returns it. The surrounding command continues
+ *     transparently;
+ *   - returns `{ status: 'missing' }` with a reason describing why no
+ *     auto-login was attempted (non-interactive, opted-out, or login
+ *     aborted by user). The caller bails with a clean message.
+ *
+ * Cross-command parity: the helper is wired into every command that
+ * needs auth (engine commands `code`/`fix`/`build`/`explain`/`plan`,
+ * plus `sync`, `chain new`, `smoke`, `review`, `deploy`, ...). The
+ * previous patchwork of `resolveActiveCredential() ?? throw` /
+ * `if (!config) writeOutput unauthenticated` calls now all funnel
+ * through here so future auth changes are one-edit.
+ *
+ * Session cache: the helper caches the resolved credential per-process.
+ * A second command in the same process never re-launches login even if
+ * the operator deletes credentials.json mid-run (that is a footgun, not
+ * a supported use case — the cached credential is still valid because
+ * the auth token in memory has not been revoked).
+ *
+ * Framework-free: the actual login call is injected via the `login`
+ * callback. The CLI passes a closure that calls
+ * `performDeviceFlowLogin` (or the interactive picker for token /
+ * env). The spec passes a fake that flips an in-memory env var so
+ * subsequent `resolveActiveCredential` calls see a credential.
+ */
+/**
+ * Process-local cache of resolved credentials. Keyed by `apiUrl` so a
+ * future `pugi accounts switch` invocation does not return stale data
+ * (different apiUrl → cache miss). Cache is additive-only.
+ */
+const credentialCache = new Map();
+/**
+ * Reset the cache. Exported for spec teardown — production callers
+ * never need this.
+ */
+export function resetAuthenticatedCache() {
+    credentialCache.clear();
+}
+/**
+ * Auth pre-flight. Returns the resolved credential or a structured
+ * `missing` envelope. The cached path skips the `resolve()` callback
+ * entirely — useful when `resolveActiveCredential` is expensive
+ * (filesystem read of ~/.pugi/credentials.json + Zod parse).
+ *
+ * Headless contract: even on a TTY, when `headless === true` the
+ * helper bails with `non_interactive`. Reason: a browser-popup login
+ * in the middle of an automated stdin → engine → stdout loop would
+ * silently freeze the run.
+ */
+export async function ensureAuthenticated(opts) {
+    // Resolve once. Cache by the resolved apiUrl so a subsequent call
+    // after `pugi accounts switch` produces a fresh resolution.
+    const initial = opts.resolve();
+    if (initial) {
+        credentialCache.set(initial.apiUrl, initial);
+        return { status: 'ready', credential: initial };
+    }
+    if (opts.skip) {
+        return {
+            status: 'missing',
+            reason: 'disabled',
+            detail: 'Authentication skipped (--no-login or PUGI_NO_AUTO_LOGIN). Run `pugi login` to authenticate.',
+        };
+    }
+    if (opts.headless) {
+        return {
+            status: 'missing',
+            reason: 'non_interactive',
+            detail: 'Headless mode cannot launch browser-popup login. Run `pugi login` once with a TTY, then re-run with --headless.',
+        };
+    }
+    if (!opts.interactive) {
+        return {
+            status: 'missing',
+            reason: 'non_interactive',
+            detail: 'No credential found and stdin is not a TTY. Run `pugi login` with a TTY OR set PUGI_API_KEY before invoking Pugi in CI.',
+        };
+    }
+    const write = opts.write ?? ((line) => process.stderr.write(line));
+    write('No Pugi credential found. Launching login...\n');
+    let succeeded;
+    try {
+        succeeded = await opts.login();
+    }
+    catch (error) {
+        return {
+            status: 'missing',
+            reason: 'login_failed',
+            detail: `Login failed: ${error.message ?? String(error)}`,
+        };
+    }
+    if (!succeeded) {
+        return {
+            status: 'missing',
+            reason: 'login_cancelled',
+            detail: 'Authentication required to continue. Run `pugi login` when ready.',
+        };
+    }
+    // Re-resolve. If a successful login was reported but no credential
+    // landed on disk, surface that as `login_failed` rather than a
+    // silent miss — would otherwise produce a confusing "you said it
+    // worked but I still see nothing" loop.
+    const resolved = opts.resolve();
+    if (!resolved) {
+        return {
+            status: 'missing',
+            reason: 'login_failed',
+            detail: 'Login reported success but no credential persisted. Check `pugi whoami`.',
+        };
+    }
+    credentialCache.set(resolved.apiUrl, resolved);
+    return { status: 'ready', credential: resolved };
+}
+//# sourceMappingURL=ensure-authenticated.js.map

package/dist/core/bash-classifier.js

@@ -367,7 +367,7 @@ const WRITE_WORKSPACE_PREFIXES = [
  * the class is `write_protected` regardless of the operation type.
  *
  * Wildcards are handled as substring matches (e.g. `/.ssh/` matches
- * `~/.ssh/foo` and `/Users/x/.ssh/bar`).
+ * `~/.ssh/foo` and `[HOME]/USER/.ssh/bar`).
  */
 const PROTECTED_PATH_SUBSTRINGS = [
     '/.ssh/',
@@ -388,6 +388,40 @@ const PROTECTED_PATH_SUBSTRINGS = [
     '/usr/',
     '/var/',
 ];
+/**
+ * Protected basename triggers — files whose CONTENT must never leak
+ * through the bash surface, even when the literal path is workspace-
+ * local. Mirrors `permission.ts::protectedBasenames` and `.env.*`
+ * pattern so the read-tool gate (which fires on `read .env`) and the
+ * bash gate (which fires on `cat .env`) stay symmetric.
+ *
+ * P0 fix 2026-05-28 (Codex audit): before this list existed, the
+ * engine model could circumvent the `read` tool's `protectedTargetReason`
+ * check by emitting `bash cat .env` — the classifier saw `cat` (read
+ * token) + `.env` (not in PROTECTED_PATH_SUBSTRINGS) and returned class
+ * `read`, which the permission matrix allows under every mode. The
+ * `local-first-invariants` spec proved the leak: `pugi explain .env`
+ * surfaced `SECRET=should_never_leak` in the engine summary.
+ *
+ * Match shape: the substring must touch a `.` boundary (`/.env`,
+ * ` .env`, `.env\b`) or appear as the full token so a path like
+ * `apps/codeforge/file.env-template` (no real secret) does not
+ * over-trigger.
+ */
+const PROTECTED_BASENAME_PATTERNS = [
+    // `.env`, `.env.production`, `.env.local` — anywhere in the command.
+    // Boundary on the left is start/whitespace/quote/`/`, on the right
+    // start/whitespace/end/quote/`>`/`|`/`;`.
+    /(^|[\s'"\/=])\.env(\.[A-Za-z0-9_-]+)?($|[\s'"<>|;&])/,
+    // SSH key basenames (covers both `id_rsa` and `id_ed25519` even
+    // outside `~/.ssh/`). The `/.ssh/` substring above gates the
+    // directory case; this catches a key file copied to the workspace.
+    /(^|[\s'"\/])id_(rsa|ed25519|ecdsa|dsa)(\.pub)?($|[\s'"<>|;&])/,
+    // Other credential basenames mirrored from permission.ts.
+    /(^|[\s'"\/])\.npmrc($|[\s'"<>|;&])/,
+    /(^|[\s'"\/])\.pypirc($|[\s'"<>|;&])/,
+    /(^|[\s'"\/])\.gitconfig($|[\s'"<>|;&])/,
+];
 /**
  * Obfuscation triggers — any of these forces the `unknown` class so
  * the permission engine can fail closed.
@@ -469,6 +503,26 @@ function classifyComponent(cmd, ctx) {
             matched: protectedRead.matched,
         };
     }
+    // 4a-bis. Parent-traversal in read arguments. The file-tools layer
+    // refuses `..` segments via `resolveWorkspacePath`, but the bash
+    // surface had no equivalent gate — the engine could emit
+    // `cat ../README.md` or `ls ..` to enumerate / read outside the
+    // workspace, sidestepping the path-security check that the `read`
+    // and `glob` tools enforce.
+    //
+    // P0 fix 2026-05-28 (Codex audit): treat `..` as a path segment
+    // (`../`, ` ..`, `..\n`) in any read-class command as a workspace
+    // escape. We classify it as `write_protected` so the auto/dontAsk
+    // modes refuse, mirroring the `Path escapes workspace` semantics
+    // the file-tools layer already provides.
+    const traversal = detectParentTraversalRead(trimmed);
+    if (traversal) {
+        return {
+            class: 'write_protected',
+            reason: traversal.reason,
+            matched: traversal.matched,
+        };
+    }
     // 4b. .env writes are always protected, even inside the workspace
     // (CEO directive feedback_never_delete_untracked_env.md).
     const envWrite = detectEnvWrite(trimmed);
@@ -785,6 +839,59 @@ function detectProtectedRead(cmd) {
             };
         }
     }
+    // P0 fix 2026-05-28: extend protected-read detection to credential
+    // basenames (`cat .env`, `head id_rsa`, `grep TOKEN .env.production`).
+    // Without this branch, the engine model can bypass the `read` tool's
+    // `protectedTargetReason` gate by emitting a bash `cat` — the read
+    // tool refuses, the model falls back to bash, and the classifier
+    // (which only knew about full-path substrings) classified `cat .env`
+    // as benign `read`. The `local-first-invariants` spec proved the leak.
+    for (const pattern of PROTECTED_BASENAME_PATTERNS) {
+        const match = cmd.match(pattern);
+        if (match) {
+            return {
+                reason: `Read from protected basename: ${match[0].trim()}`,
+                matched: match[0].trim(),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Detect parent-traversal segments (`..`) inside read-class commands.
+ * The file-tools layer (`resolveWorkspacePath`) refuses these for the
+ * `read`/`glob`/`grep` tools, but bash had no equivalent gate. We
+ * trigger on the SAME shape `path-security.ts` rejects: a `..` segment
+ * separated by `/` or whitespace. Quoted/escaped variants get the same
+ * treatment.
+ *
+ * Returns null on the safe path (no `..` segment) so the caller falls
+ * through to the regular read classification.
+ */
+function detectParentTraversalRead(cmd) {
+    const firstToken = cmd.split(/\s+/)[0] ?? '';
+    const isReadTool = READ_TOKENS.has(firstToken) ||
+        READ_PREFIX_TOKENS.has(firstToken) ||
+        firstToken === 'sed' ||
+        firstToken === 'awk' ||
+        firstToken === 'find';
+    if (!isReadTool)
+        return null;
+    // Match `..` as a path segment: preceded by start/whitespace/quote/`/`
+    // and followed by `/`, end-of-string, whitespace, or shell metas.
+    // Avoids over-matching `v1..v2` (range syntax inside a single token)
+    // and `1..5` (numeric ranges) because those lack the path boundary.
+    const traversalPattern = /(^|[\s'"\/])\.\.(\/|$|[\s'"<>|;&])/;
+    const m = cmd.match(traversalPattern);
+    if (m) {
+        return {
+            reason: 'Read command escapes workspace via parent traversal',
+            matched: '..',
+        };
+    }
+    // Absolute path read of /etc, /usr, /var, etc is already covered by
+    // PROTECTED_PATH_SUBSTRINGS in detectProtectedRead — no extra branch
+    // needed here.
     return null;
 }
 function detectEnvWrite(cmd) {

package/dist/core/codegraph/decision-store.js

@@ -0,0 +1,248 @@
+/**
+ * Codegraph install-decision store — Wave 6 BIG TRACK 9 Phase 2.
+ *
+ * Persists the operator's verdict on the codegraph install prompt so we
+ * never spam them after a single decline. The 30-day reminder cadence
+ * lets us re-surface the offer on big-enough repos in case the operator
+ * said "not now" the first time and then forgot codegraph exists.
+ *
+ * Schema (workspace-scoped at `.pugi/codegraph-decision.json`):
+ *
+ *   {
+ *     "schema": 1,
+ *     "offeredAt": "2026-05-27T00:00:00.000Z",
+ *     "accepted": false,
+ *     "decliningCount": 1,
+ *     "remindAfter": "2026-06-26T00:00:00.000Z",  // 30 days from offeredAt
+ *     "lastIndexedAt": null,                        // ISO date string OR null
+ *     "lastReindexCheckAt": null
+ *   }
+ *
+ * The store is workspace-local (each repo gets its own decision) so
+ * declining codegraph in repo A does not suppress the prompt in repo B.
+ * `.pugi/` already exists by the time we land here (pugi init scaffolds
+ * it), so the directory creation is best-effort defence-in-depth.
+ *
+ * Concurrency: every write is `tmp + rename` so a partial write cannot
+ * surface a corrupt JSON. Reads tolerate missing files + corrupt JSON
+ * by returning `null` — the caller decides whether to fall back to
+ * "offer again" (safe default) or "do nothing" (cold-start path).
+ *
+ * Pure persistence. No telemetry, no logging. The emitter lives in the
+ * call sites so the decision store stays unit-testable in isolation.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Reminder cadence — 30 days from the last decline. Operators who said
+ * no in a small repo that grew к medium during a sprint deserve a
+ * follow-up; operators who said no last week do not. The window is
+ * exposed as a const so the spec can pin it.
+ */
+export const REMIND_AFTER_DAYS = 30;
+/**
+ * Stale-index threshold for the cold-start "refresh me" reminder.
+ * Seven days is the cadence the upstream codegraph docs recommend for
+ * monorepos that ship multiple times a day; lower repos can wait
+ * longer. The spec pins it.
+ */
+export const STALE_INDEX_DAYS = 7;
+/**
+ * Resolve the decision file path for a workspace root. Pure — exposed
+ * для spec parity.
+ */
+export function decisionPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.pugi/codegraph-decision.json');
+}
+/**
+ * Read the persisted decision. Returns null on missing file, malformed
+ * JSON, or wrong schema version. The caller MUST treat null as "no
+ * decision yet" — not "operator declined".
+ */
+export function readDecision(workspaceRoot) {
+    const path = decisionPath(workspaceRoot);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isDecisionShape(parsed))
+        return null;
+    return parsed;
+}
+/**
+ * Type guard. Defensive — a future schema bump should land a migration
+ * here. For now: schema MUST be 1; required string fields MUST be
+ * strings; optional fields may be null OR string.
+ */
+function isDecisionShape(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    if (v.schema !== 1)
+        return false;
+    if (typeof v.offeredAt !== 'string')
+        return false;
+    if (typeof v.accepted !== 'boolean')
+        return false;
+    if (typeof v.decliningCount !== 'number' || !Number.isFinite(v.decliningCount))
+        return false;
+    if (typeof v.remindAfter !== 'string')
+        return false;
+    if (v.lastIndexedAt !== null && typeof v.lastIndexedAt !== 'string')
+        return false;
+    if (v.lastReindexCheckAt !== null && typeof v.lastReindexCheckAt !== 'string')
+        return false;
+    return true;
+}
+/**
+ * Atomic write. Creates `.pugi/` if it does not exist (pugi init owns
+ * that surface ordinarily; we defend the rare cold-start path).
+ */
+export function writeDecision(workspaceRoot, decision) {
+    const path = decisionPath(workspaceRoot);
+    const dir = resolve(workspaceRoot, '.pugi');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, `${JSON.stringify(decision, null, 2)}\n`, { mode: 0o600 });
+    try {
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        // Rename can fail if the destination was concurrently swapped on
+        // some platforms (Windows). Fall back to unlink + rename so the
+        // best-effort write does not throw to the caller.
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // ignore
+        }
+        renameSync(tmp, path);
+        void error;
+    }
+}
+/**
+ * Decide whether to surface the install prompt on init. Returns the
+ * full decision shape for callers that want to inspect the cadence;
+ * a `true` verdict means "yes, ask the operator now".
+ */
+export function shouldOfferOnInit(workspaceRoot, nowIso = new Date().toISOString()) {
+    const prior = readDecision(workspaceRoot);
+    if (!prior) {
+        return { shouldOffer: true, reason: 'first-run' };
+    }
+    if (prior.accepted) {
+        return { shouldOffer: false, reason: 'accepted-already' };
+    }
+    if (Date.parse(nowIso) >= Date.parse(prior.remindAfter)) {
+        return { shouldOffer: true, reason: 'reminder-due' };
+    }
+    return { shouldOffer: false, reason: 'recent-decline' };
+}
+/**
+ * Record the operator's decision atomically. Mirrors the structure on
+ * disk — callers do NOT hand-craft the schema.
+ */
+export function recordDecision(workspaceRoot, input) {
+    const nowIso = input.nowIso ?? new Date().toISOString();
+    const prior = readDecision(workspaceRoot);
+    const decliningCount = input.accepted ? 0 : (prior?.decliningCount ?? 0) + 1;
+    const remindAfter = new Date(Date.parse(nowIso) + REMIND_AFTER_DAYS * 24 * 60 * 60 * 1000).toISOString();
+    const decision = {
+        schema: 1,
+        offeredAt: nowIso,
+        accepted: input.accepted,
+        decliningCount,
+        remindAfter,
+        lastIndexedAt: prior?.lastIndexedAt ?? null,
+        lastReindexCheckAt: prior?.lastReindexCheckAt ?? null,
+    };
+    writeDecision(workspaceRoot, decision);
+    return decision;
+}
+/**
+ * Stamp the last-indexed timestamp. Called by /codegraph-status when
+ * the operator triggers a reindex from inside Pugi. Updates the
+ * `accepted` decision in place — never flips the install state.
+ */
+export function markIndexed(workspaceRoot, nowIso = new Date().toISOString()) {
+    const prior = readDecision(workspaceRoot);
+    if (!prior)
+        return null;
+    const next = {
+        ...prior,
+        lastIndexedAt: nowIso,
+        lastReindexCheckAt: nowIso,
+    };
+    writeDecision(workspaceRoot, next);
+    return next;
+}
+/**
+ * Stamp the last reindex-check timestamp without changing the index
+ * itself. Used by the cold-start hook so we do not show the "index is
+ * stale" hint on every keystroke once the operator has acknowledged
+ * it.
+ */
+export function markReindexChecked(workspaceRoot, nowIso = new Date().toISOString()) {
+    const prior = readDecision(workspaceRoot);
+    if (!prior)
+        return null;
+    const next = {
+        ...prior,
+        lastReindexCheckAt: nowIso,
+    };
+    writeDecision(workspaceRoot, next);
+    return next;
+}
+/**
+ * Compute the staleness of the codegraph index. Pure — no IO.
+ *
+ *   - returns null when `lastIndexedAt` is null (never indexed)
+ *   - returns the day-delta (rounded down) otherwise
+ */
+export function indexAgeDays(decision, nowIso = new Date().toISOString()) {
+    if (!decision.lastIndexedAt)
+        return null;
+    const deltaMs = Date.parse(nowIso) - Date.parse(decision.lastIndexedAt);
+    if (!Number.isFinite(deltaMs) || deltaMs < 0)
+        return 0;
+    return Math.floor(deltaMs / (24 * 60 * 60 * 1000));
+}
+/**
+ * Convenience predicate — should the cold-start hook show the stale-
+ * index reminder? `true` when the index is older than STALE_INDEX_DAYS
+ * AND we did NOT already remind the operator today.
+ */
+export function shouldNudgeStaleIndex(decision, nowIso = new Date().toISOString()) {
+    if (!decision.accepted)
+        return false;
+    const age = indexAgeDays(decision, nowIso);
+    if (age === null)
+        return false;
+    if (age < STALE_INDEX_DAYS)
+        return false;
+    // Throttle the nudge to once per day so the operator does not see it
+    // on every REPL keystroke.
+    if (decision.lastReindexCheckAt) {
+        const lastCheckDelta = Date.parse(nowIso) - Date.parse(decision.lastReindexCheckAt);
+        if (Number.isFinite(lastCheckDelta) && lastCheckDelta < 24 * 60 * 60 * 1000) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=decision-store.js.map