peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/skillhub/sqlite-store.d.ts

@@ -0,0 +1,22 @@
+import Database from "better-sqlite3";
+/**
+ * Open (or create) a SkillHub state database at the given path.
+ *
+ * Behavior:
+ *   - Creates the parent directory if it does not exist.
+ *   - Enables WAL journal mode and foreign-key enforcement.
+ *   - Applies every `migrations/*.sql` file in lexicographic order.
+ *     Migrations must be idempotent (CREATE TABLE IF NOT EXISTS, etc.).
+ *
+ * The migrations directory lives next to this source file at build time;
+ * we resolve it via `import.meta.url` so the lookup survives vitest ESM
+ * (where `__dirname` is undefined). Migration files are discovered by
+ * globbing (`*.sql`) and sorted lexicographically so future
+ * `002-…`, `003-…` additions are picked up automatically.
+ */
+export declare function openStateDb(path: string): Database.Database;
+/**
+ * Return the user-defined table names present in `db` (excluding SQLite
+ * system tables such as `sqlite_sequence`).
+ */
+export declare function listTables(db: Database.Database): string[];

package/dist/services/skillhub/sqlite-store.js

@@ -0,0 +1,63 @@
+import Database from "better-sqlite3";
+import { readFileSync, readdirSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Open (or create) a SkillHub state database at the given path.
+ *
+ * Behavior:
+ *   - Creates the parent directory if it does not exist.
+ *   - Enables WAL journal mode and foreign-key enforcement.
+ *   - Applies every `migrations/*.sql` file in lexicographic order.
+ *     Migrations must be idempotent (CREATE TABLE IF NOT EXISTS, etc.).
+ *
+ * The migrations directory lives next to this source file at build time;
+ * we resolve it via `import.meta.url` so the lookup survives vitest ESM
+ * (where `__dirname` is undefined). Migration files are discovered by
+ * globbing (`*.sql`) and sorted lexicographically so future
+ * `002-…`, `003-…` additions are picked up automatically.
+ */
+export function openStateDb(path) {
+    const parent = dirname(path);
+    if (!existsSync(parent))
+        mkdirSync(parent, { recursive: true });
+    const db = new Database(path);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    const here = dirname(fileURLToPath(import.meta.url));
+    const migrationsDir = join(here, "migrations");
+    if (existsSync(migrationsDir)) {
+        const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql")).sort();
+        for (const f of files) {
+            const sql = readFileSync(join(migrationsDir, f), "utf-8");
+            try {
+                db.exec(sql);
+            }
+            catch (err) {
+                // Tolerate idempotent re-runs of `ALTER TABLE ... ADD COLUMN`
+                // migrations (e.g. 004-loop-bee-extension). The migration
+                // files themselves are NOT idempotent (SQLite has no
+                // `ALTER TABLE ADD COLUMN IF NOT EXISTS`); the runner is
+                // made idempotent here so the same state.db can be opened
+                // by multiple CLI processes within one workflow.
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("duplicate column name") ||
+                    msg.includes("already exists")) {
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    return db;
+}
+/**
+ * Return the user-defined table names present in `db` (excluding SQLite
+ * system tables such as `sqlite_sequence`).
+ */
+export function listTables(db) {
+    const rows = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+        .all();
+    return rows.map((r) => r.name);
+}

package/dist/services/skillhub/tar-runtime.d.ts

@@ -0,0 +1,21 @@
+/** Thrown when no usable tar binary can be located. */
+export declare class TAR_NOT_FOUND extends Error {
+    constructor(msg: string);
+}
+/**
+ * Run `tar <args...>` in a cross-platform way.
+ *
+ * Args MUST be `["-czf", outPath, "-C", stageDir, "."]` style (no
+ * shell quoting needed because we use execFileSync, not execSync).
+ *
+ * After the Critical #3 fix:
+ *   - Honors PEAKS_TAR_BIN / TAR env vars.
+ *   - On Windows, tries C:\Windows\System32\tar.exe first; falls back
+ *     to PATH lookup if it's missing.
+ *   - Accumulates tar's stderr and re-throws it on non-zero exit so
+ *     operators can see WHY tar failed (path typo, permission, corrupt
+ *     stage dir, etc.) instead of swallowing it.
+ *
+ * Throws `TAR_NOT_FOUND` when the binary cannot be located.
+ */
+export declare function runTar(args: string[]): void;

package/dist/services/skillhub/tar-runtime.js

@@ -0,0 +1,91 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+/** Thrown when no usable tar binary can be located. */
+export class TAR_NOT_FOUND extends Error {
+    constructor(msg) {
+        super(`TAR_NOT_FOUND: ${msg}`);
+        this.name = "TAR_NOT_FOUND";
+    }
+}
+/**
+ * Resolve a tar binary path, in priority order:
+ *   1. process.env.PEAKS_TAR_BIN  (explicit override; honored unconditionally)
+ *   2. process.env.TAR            (POSIX convention, honored if set)
+ *   3. On Windows: C:\Windows\System32\tar.exe (bsdtar — accepts
+ *      Windows-style paths verbatim, unlike git-bash GNU tar)
+ *   4. PATH lookup: "tar" (delegates to the platform default)
+ *
+ * Throws `TAR_NOT_FOUND` when none of the candidates exist (Windows
+ * file-system check) or no override is set (POSIX). On POSIX we
+ * always trust PATH; tar is in base images 99.9% of the time. On
+ * Windows we explicitly stat each candidate so a missing
+ * C:\Windows\System32\tar.exe falls through to PATH instead of
+ * throwing an opaque spawn-ENOENT.
+ */
+function resolveTarBin() {
+    const envOverride = process.env.PEAKS_TAR_BIN;
+    if (envOverride && envOverride.length > 0)
+        return envOverride;
+    const envTar = process.env.TAR;
+    if (envTar && envTar.length > 0)
+        return envTar;
+    if (process.platform === "win32") {
+        const systemTar = "C:\\Windows\\System32\\tar.exe";
+        if (existsSync(systemTar))
+            return systemTar;
+        // Fall through to PATH lookup below — many dev setups install tar
+        // under Git for Windows or WindowsApps rather than System32.
+    }
+    // PATH lookup. We can't stat `tar` directly (it's a name, not a path),
+    // so we trust the resolution to execFileSync and surface a clean
+    // TAR_NOT_FOUND error from the caller if it fails.
+    return "tar";
+}
+/**
+ * Run `tar <args...>` in a cross-platform way.
+ *
+ * Args MUST be `["-czf", outPath, "-C", stageDir, "."]` style (no
+ * shell quoting needed because we use execFileSync, not execSync).
+ *
+ * After the Critical #3 fix:
+ *   - Honors PEAKS_TAR_BIN / TAR env vars.
+ *   - On Windows, tries C:\Windows\System32\tar.exe first; falls back
+ *     to PATH lookup if it's missing.
+ *   - Accumulates tar's stderr and re-throws it on non-zero exit so
+ *     operators can see WHY tar failed (path typo, permission, corrupt
+ *     stage dir, etc.) instead of swallowing it.
+ *
+ * Throws `TAR_NOT_FOUND` when the binary cannot be located.
+ */
+export function runTar(args) {
+    const cmd = resolveTarBin();
+    try {
+        execFileSync(cmd, args, {
+            stdio: ["ignore", "ignore", "pipe"],
+            // Surface stderr text rather than dumping a Buffer at the caller.
+            // execFileSync with stdio: ["ignore","ignore","pipe"] captures the
+            // stderr stream into the Error's `.stderr` Buffer when the child
+            // exits non-zero.
+        });
+    }
+    catch (e) {
+        // Distinguish "binary not found" from "binary ran but failed".
+        if (e && typeof e === "object" && "code" in e) {
+            const code = e.code;
+            if (code === "ENOENT") {
+                throw new TAR_NOT_FOUND(`tar binary not found (cmd="${cmd}"). Set PEAKS_TAR_BIN to override, or install tar (Windows: bsdtar is bundled with Windows 10+).`);
+            }
+        }
+        // Non-zero exit from tar itself — re-throw with stderr text.
+        const stderr = e?.stderr;
+        const stderrText = stderr instanceof Buffer
+            ? stderr.toString("utf-8")
+            : typeof stderr === "string"
+                ? stderr
+                : "";
+        const baseMsg = e instanceof Error ? e.message : typeof e === "string" ? e : String(e);
+        const wrapped = new Error(`tar exited non-zero (cmd="${cmd}"): ${baseMsg}${stderrText ? `\ntar stderr:\n${stderrText.trimEnd()}` : ""}`);
+        wrapped.cause = e;
+        throw wrapped;
+    }
+}

package/dist/services/skillhub/types.d.ts

@@ -0,0 +1,115 @@
+export interface BeeReleaseRow {
+    id: number;
+    bee_name: string;
+    version: string;
+    source: "user";
+    archived_at: string;
+    archived_by: "user" | "llm";
+    user_intent_raw: string | null;
+    description: string | null;
+    parent_version: string | null;
+    changelog: string | null;
+    /**
+     * M3 / spec §4.2: `shareable` defaults to true (1 in SQLite).
+     * Enforced at the export CLI layer in M7; M3 only adds the column.
+     */
+    shareable: 0 | 1;
+    /**
+     * M3 / spec §4.2: `desktop_visible` defaults to true (1 in SQLite).
+     * Desktop visibility is a UI accelerator filter; M7 reads this.
+     */
+    desktop_visible: 0 | 1;
+}
+export interface BeeReleasePointerRow {
+    bee_name: string;
+    latest_version: string;
+    released_at: string;
+}
+export interface BeeManifestRow {
+    release_id: number;
+    schema_version: string;
+    description: string;
+    segments_json: string;
+    entrypoint_preamble: string | null;
+    promotion: string;
+    min_cycles: number | null;
+    requires_human: number;
+    requires_smoke: number;
+    retire_on_misses: number | null;
+}
+export interface BeeSegmentRefRow {
+    id: number;
+    release_id: number;
+    segment_name: string;
+    inputs_json: string | null;
+    outputs_json: string | null;
+    side_effects: string | null;
+}
+export interface BeeFileRow {
+    id: number;
+    release_id: number;
+    owner_kind: "bee" | "segment";
+    owner_name: string;
+    path: string;
+    kind: "markdown" | "script" | "reference" | "binary" | "other";
+    size_bytes: number;
+    sha256: string;
+    blob_path: string;
+}
+export interface BeeChangeRow {
+    id: number;
+    release_id: number;
+    change_kind: string;
+    target_kind: string;
+    target_name: string;
+    detail: string | null;
+}
+/**
+ * Shape of `manifest.json` inside a release export tarball.
+ *
+ * Producer: `src/services/skillhub/release-export.ts` writes this file via
+ *   `JSON.stringify({ bee_name, version, manifestRows, segRows, fileRows, changeRows })`.
+ * Consumer: `src/services/skillhub/release-import.ts` parses it back with
+ *   `JSON.parse(readFileSync(join(stageDir, "manifest.json"), "utf-8"))`.
+ *
+ * Defining it once here (rather than as an inline anonymous type at the
+ * call-site) lets both sides share a structural contract. If a future
+ * field is added — e.g. an exported schema-version stamp — it lands in
+ * one place and TypeScript flags every consumer that needs updating.
+ */
+export interface ExportPayload {
+    bee_name: string;
+    version: string;
+    manifestRows: Array<{
+        schema_version: string;
+        description: string;
+        segments_json: string;
+        entrypoint_preamble: string | null;
+        promotion: string;
+        min_cycles: number | null;
+        requires_human: number;
+        requires_smoke: number;
+        retire_on_misses: number | null;
+    }>;
+    segRows: Array<{
+        segment_name: string;
+        inputs_json: string | null;
+        outputs_json: string | null;
+        side_effects: string | null;
+    }>;
+    fileRows: Array<{
+        owner_kind: string;
+        owner_name: string;
+        path: string;
+        kind: string;
+        size_bytes: number;
+        sha256: string;
+        blob_path: string;
+    }>;
+    changeRows: Array<{
+        change_kind: string;
+        target_kind: string;
+        target_name: string;
+        detail: string | null;
+    }>;
+}

package/dist/services/skillhub/types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/skills/skill-conformance-service.js

@@ -0,0 +1,139 @@
+/**
+ * Skill-conformance audit (Slice #12) — checks every peaks-* SKILL.md
+ * against the 5 standards from the L1+L2+L3 redesign §5.4 Slice #12:
+ *
+ *   1. task-level frontmatter (all 12 skills must declare one)
+ *   2. CLI-back 注解 coverage (each skill body must document which
+ *      `peaks <cmd>` commands it composes; the absence is a SKILL.md
+ *      anti-pattern — it means the LLM has to discover the CLI
+ *      primitives by accident)
+ *   3. loadStrategy on-demand 标注 (skills should declare when they
+ *      load — `eager` for always-loaded, `on-demand` for invoked)
+ *   4. 800-line cap (Karpathy limit per spec §2.3)
+ *   5. outputStyle: peaks-concise-v1 frontmatter (peak-cli display
+ *      style for the skill's user-visible output)
+ *
+ * Plus 1 derived check:
+ *   6. CLI primitives declared in references/audit/ (Skill must
+ *      surface every peaks <cmd> it composes in the references/ subdir;
+ *      this is the "CLI-back 注解 100% 覆盖" check)
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const SKILL_NAMES = [
+    'peaks-ide',
+    'peaks-prd',
+    'peaks-ui',
+    'peaks-rd',
+    'peaks-qa',
+    'peaks-sc',
+    'peaks-code',
+    'peaks-resume',
+    'peaks-status',
+    'peaks-test',
+    'peaks-sop',
+    'peaks-txt',
+    'peaks-doctor'
+];
+const REQUIRED_FRONTMATTER_FIELDS = ['name', 'description'];
+const OPTIONAL_FRONTMATTER_FIELDS = ['task-level', 'loadStrategy', 'outputStyle'];
+const MAX_LINE_COUNT = 800;
+const CLI_BACK_PATTERNS = [
+    /`peaks\s+[a-z][a-z0-9-]+(?:\s+[a-z][a-z0-9-]+)*`/g,
+    /`peaks\s+[a-z][a-z0-9-]+/g,
+];
+function readSkillFrontmatter(skillPath) {
+    if (!existsSync(skillPath))
+        return null;
+    const content = readFileSync(skillPath, 'utf-8');
+    const match = /^---\n([\s\S]*?)\n---\n/.exec(content);
+    if (match === null)
+        return { raw: content, fields: {} };
+    const raw = match[1] ?? '';
+    const fields = {};
+    for (const line of raw.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim();
+        if (key.length > 0)
+            fields[key] = value;
+    }
+    return { raw, fields };
+}
+function lineCount(filePath) {
+    try {
+        return statSync(filePath).size > 0 ? readFileSync(filePath, 'utf-8').split(/\r?\n/).length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function countCliBackReferences(content) {
+    let count = 0;
+    for (const pattern of CLI_BACK_PATTERNS) {
+        pattern.lastIndex = 0;
+        const matches = content.match(pattern);
+        if (matches)
+            count += matches.length;
+    }
+    return count;
+}
+export function auditSkillConformance(input) {
+    const skillsDir = join(input.projectRoot, 'skills');
+    const checks = [];
+    for (const skillName of SKILL_NAMES) {
+        // LLM-internal skills live under `skills/bee/<name>/` per spec 2026-07-05.
+        const topPath = join(skillsDir, skillName, 'SKILL.md');
+        const beePath = join(skillsDir, 'bee', skillName, 'SKILL.md');
+        const skillPath = existsSync(topPath) ? topPath : beePath;
+        const fm = readSkillFrontmatter(skillPath);
+        // 1. task-level frontmatter
+        if (fm === null) {
+            checks.push({ id: 'frontmatter:present', skill: skillName, level: 'fail', message: 'SKILL.md missing' });
+        }
+        else {
+            for (const required of REQUIRED_FRONTMATTER_FIELDS) {
+                if (fm.fields[required] === undefined) {
+                    checks.push({ id: `frontmatter:${required}`, skill: skillName, level: 'fail', message: `frontmatter missing required field "${required}"` });
+                }
+            }
+        }
+        // 2. CLI-back annotation
+        if (fm !== null) {
+            const content = readFileSync(skillPath, 'utf-8');
+            const cliCount = countCliBackReferences(content);
+            if (cliCount === 0) {
+                checks.push({ id: 'cli-back:present', skill: skillName, level: 'warn', message: 'no `peaks <cmd>` references in SKILL.md body; consider documenting which CLI primitives the skill composes' });
+            }
+        }
+        // 3. loadStrategy on-demand 标注
+        if (fm !== null && fm.fields['loadStrategy'] === undefined) {
+            checks.push({ id: 'loadStrategy:declared', skill: skillName, level: 'warn', message: 'loadStrategy not declared in frontmatter (eager | on-demand)' });
+        }
+        // 4. 800-line cap
+        if (fm !== null) {
+            const lines = lineCount(skillPath);
+            if (lines > MAX_LINE_COUNT) {
+                checks.push({ id: 'line-count:cap', skill: skillName, level: 'fail', message: `${lines} lines > ${MAX_LINE_COUNT} cap (Karpathy)` });
+            }
+        }
+        // 5. outputStyle: peaks-concise-v1
+        if (fm !== null && fm.fields['outputStyle'] === undefined) {
+            checks.push({ id: 'outputStyle:declared', skill: skillName, level: 'warn', message: 'outputStyle not declared in frontmatter' });
+        }
+    }
+    const failed = checks.filter((c) => c.level === 'fail').length;
+    const warned = checks.filter((c) => c.level === 'warn').length;
+    const passed = checks.filter((c) => c.level === 'pass').length;
+    return {
+        checked: checks.length,
+        passed,
+        warned,
+        failed,
+        checks,
+        summary: failed === 0 ? 'all hard checks pass; warnings are advisory' : `${failed} hard failure(s); fix before shipping`,
+    };
+}

package/dist/services/skills/skill-presence-service.d.ts

@@ -0,0 +1,158 @@
+export type SkillPresenceMode = 'full-auto' | 'assisted' | 'swarm' | 'strict';
+export declare const VALID_SKILL_PRESENCE_MODES: ReadonlyArray<SkillPresenceMode>;
+export declare function isSkillPresenceMode(value: string): value is SkillPresenceMode;
+export type SkillPresence = {
+    skill: string;
+    mode?: SkillPresenceMode;
+    gate?: string;
+    sessionId?: string;
+    /**
+     * Identifier of the *outer* session — the Claude Code / Cursor /
+     * VSCode-plugin / other harness session that is currently driving
+     * the LLM. Sourced from the `PEAKS_OUTER_SESSION_ID` environment
+     * variable when set, with `CLAUDE_CODE_SESSION_ID` as a fallback for
+     * Claude Code. Stamped onto the presence file so the status line
+     * can tell whether the recorded skill belongs to the live outer
+     * session (show it) or a previous one (render idle), and so
+     * `setSkillPresence` can detect a session swap and AskUserQuestion
+     * the user about rolling a new peaks session.
+     */
+    outerSessionId?: string;
+    /**
+     * Set by `setSkillPresence` when the outer session id changed
+     * between the last presence write and this one AND the bound
+     * peaks session has a different (or no) recorded outer session id.
+     *
+     * As of slice 018 (auto-roll on outer-mismatch), the field is
+     * informational only — it tells the statusline and any log /
+     * observability consumer that an outer-session swap was observed
+     * on the previous heartbeat. The actual binding rotation is
+     * performed by `ensureSessionWithRotation` (slice 018), not by
+     * `setSkillPresence`. `peaks-code`'s Step 0 used to read this
+     * field and turn it into an AskUserQuestion; that ask is no
+     * longer needed because the rotation already happened by the time
+     * the skill is invoked.
+     */
+    outerSessionMismatch?: {
+        previous?: string;
+        current: string;
+        boundSessionId: string;
+        boundOuterSessionId?: string;
+    };
+    setAt: string;
+    lastHeartbeat?: string;
+};
+/**
+ * Resolve the active peaks session id from
+ * `.peaks/_runtime/session.json` (legacy: `.peaks/.session.json`).
+ * Returns `null` when no session is bound.
+ *
+ * Public export: callers like `peaks sub-agent dispatch` use this
+ * to auto-resolve `--session-id` when the LLM driver forgets to
+ * pass the flag, so dispatch records land in the right
+ * `.peaks/_sub_agents/<sid>/` tree instead of an `unknown-sid`
+ * fallback (slice 2026-06-26-unknown-sid-fallback-fix).
+ */
+export declare function getCurrentSessionId(projectRootOverride?: string): string | null;
+export declare function exportSkillPresence(projectRootOverride?: string): string;
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export declare function setSkillPresenceForCaller(projectRootOverride: string, callerId: string, peakSessionId: string, skill: string, mode?: string, gate?: string): SkillPresence;
+export declare function setSkillPresence(skill: string, mode?: string, gate?: string, projectRootOverride?: string): SkillPresence;
+export declare function getSkillPresence(projectRootOverride?: string): SkillPresence | null;
+/**
+ * Slice 002 (v2.15.0) — presence staleness detection (AC-1).
+ *
+ * Compare the *outer* session id stamped onto the current presence
+ * marker against the *current* outer session id (from
+ * `PEAKS_OUTER_SESSION_ID` / `CLAUDE_CODE_SESSION_ID`).
+ *
+ * Stale reasons (in priority order):
+ *
+ *   - `'outer-session-mismatch'` — the presence was stamped by a
+ *     different outer (Claude / harness) session than the one that
+ *     is now driving peaks. Most common cause: the LLM closed the
+ *     previous Claude session, the next session boots and finds a
+ *     presence leftover from the old one. peaks-code Step 1 must
+ *     AskUserQuestion to confirm the user wants the old mode.
+ *
+ *   - `'no-presence'`            — there is no presence file on disk.
+ *     Not strictly "stale", but callers (peaks-code Step 1, `peaks
+ *     code should-pause --step step-1-mode-select`) want to treat
+ *     this case as "no opinion yet — must ask". Surfaced as
+ *     `stale: true` with reason `'no-presence'` so the ask path is
+ *     uniform.
+ *
+ *   - `null`                     — the presence exists AND its outer
+ *     session id matches the current outer session id. Not stale.
+ *     Caller may safely reuse the recorded mode.
+ *
+ * Pure read-only: never deletes the presence file (the rotation
+ * auto-clear path is a separate concern; see
+ * `clearStalePresenceOnRotation`). Test seam: `--current-outer` lets
+ * tests inject a deterministic current outer id without touching env
+ * vars.
+ */
+export type StaleReason = 'outer-session-mismatch' | 'no-presence';
+export type StalenessCheck = {
+    stale: boolean;
+    reason: StaleReason | null;
+    /** What was on disk; null when no presence was found. */
+    presence: SkillPresence | null;
+    /** Current outer session id (env-driven). Undefined when no signal. */
+    currentOuterSessionId: string | undefined;
+    /** Outer session id recorded on the presence marker. Undefined when no signal. */
+    recordedOuterSessionId: string | undefined;
+};
+export declare function checkStalePresence(opts?: {
+    projectRootOverride?: string | undefined;
+    /**
+     * Override the *current* outer session id. Test seam only.
+     *   - `undefined` (omitted): read from `PEAKS_OUTER_SESSION_ID` /
+     *     `CLAUDE_CODE_SESSION_ID` env vars.
+     *   - explicit `string`: use the value verbatim (empty string means
+     *     "no signal", same as a missing env var).
+     */
+    currentOuter?: string | undefined;
+}): StalenessCheck;
+/**
+ * Slice 002 (v2.15.0) — auto-clear stale presence on session
+ * rotation (AC-1).
+ *
+ * Called from `peaks workspace init` immediately after a successful
+ * `outer-session-mismatch` rotation. When the previous session's
+ * presence is still on disk under the OLD outer session id,
+ * clearing it prevents peaks-code Step 1 from picking up a stale
+ * `mode` field that the user never explicitly chose.
+ *
+ * Only clears when:
+ *   - the recorded outer session id does NOT match the current outer
+ *     session id (i.e. the presence IS stale), AND
+ *   - the recorded outer session id matches the just-rotated-out
+ *     session id (i.e. we're clearing exactly the old binding, not a
+ *     user-explicitly-set mode from another live outer session).
+ *
+ * Returns `{ cleared, reason }` so callers can surface the outcome
+ * in the JSON envelope and audit log. Pure: no env-var reads, all
+ * inputs are passed explicitly so the call site (init command) can
+ * decide what the "rotated-out" id was.
+ */
+export declare function clearStalePresenceOnRotation(opts: {
+    projectRootOverride?: string;
+    currentOuterSessionId: string | undefined;
+    rotatedOutSessionId: string | null;
+}): {
+    cleared: boolean;
+    reason: string | null;
+    recordedOuter?: string;
+};
+export declare function touchSkillHeartbeat(projectRootOverride?: string): SkillPresence | null;
+export declare function clearSkillPresence(projectRootOverride?: string): boolean;