peaks-loop 4.1.2 → 4.1.3

package/dist/cli/commands/core/skill-generated-config-notice.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonicalize a user-supplied `--project <path>` value.
+ *
+ * Git Bash on Windows hands us forward-slash paths
+ * (`C:/Users/.../peaks-loop`) while `peaks workspace init` writes the
+ * backslash form, and either side may carry a trailing separator or
+ * differing case. Resolving to the real path here means every
+ * downstream consumer (`getSessionId`, `setSessionMeta`,
+ * `setSkillPresence`) sees one stable form.
+ *
+ * Returns the input unchanged when it cannot be resolved (path does
+ * not exist yet, or is not readable) so a bad `--project` still
+ * reaches the existing error handling rather than throwing here.
+ */
+export declare function canonicalizeProjectOption(project: string | undefined): string | undefined;
+/**
+ * D1 (2026-09-15) — generated-config staleness, carried on `skill presence`.
+ *
+ * WHY THIS CALL. `npm i -g peaks-loop@<newer>` upgrades the CLI and leaves the
+ * project's generated config exactly as the OLD release wrote it:
+ * `initWorkspace` is the only writer and `ensureSession` early-returns once a
+ * session is bound, so nothing re-runs the generator. `.claude/settings.local.json`
+ * is drift-checked — but only on an init that never comes. The user found the
+ * previous instance of this by deleting their `.claude/*.json` and restarting;
+ * nothing in the product told them to.
+ *
+ * `peaks skill presence` is the ONE peaks call every skill makes in every turn
+ * (CLAUDE.md mandates it at the start of every response), so it is the only
+ * channel guaranteed to carry a drift notice to the LLM that can act on it —
+ * the same reasoning as the loop-hygiene verdict attached one screen down. A
+ * rule that lives only in a SKILL.md body is compacted away; a warning that
+ * rides the per-turn tool output is not.
+ *
+ * The field is additive and present only when stale, so no existing consumer
+ * of the envelope changes shape. `null` projectRoot means the caller had no
+ * project to inspect — skipped, not assumed stale.
+ */
+export declare function generatedConfigNotice(projectRoot: string | undefined): {
+    field: Record<string, unknown>;
+    warnings: string[];
+};

package/dist/cli/commands/core/skill-generated-config-notice.js

@@ -0,0 +1,75 @@
+// Split out of `core/skill-command.ts`:
+// `--project` canonicalization plus the D1 generated-config staleness notice
+// that rides the per-turn `peaks skill presence` read.
+import { stableRealPath } from '../../../shared/path-utils.js';
+import { detectStaleGeneratedArtifacts } from '../../../services/workspace/generated-artifacts-stamp.js';
+/**
+ * Canonicalize a user-supplied `--project <path>` value.
+ *
+ * Git Bash on Windows hands us forward-slash paths
+ * (`C:/Users/.../peaks-loop`) while `peaks workspace init` writes the
+ * backslash form, and either side may carry a trailing separator or
+ * differing case. Resolving to the real path here means every
+ * downstream consumer (`getSessionId`, `setSessionMeta`,
+ * `setSkillPresence`) sees one stable form.
+ *
+ * Returns the input unchanged when it cannot be resolved (path does
+ * not exist yet, or is not readable) so a bad `--project` still
+ * reaches the existing error handling rather than throwing here.
+ */
+export function canonicalizeProjectOption(project) {
+    if (project === undefined)
+        return undefined;
+    try {
+        return stableRealPath(project);
+    }
+    catch {
+        return project;
+    }
+}
+/**
+ * D1 (2026-09-15) — generated-config staleness, carried on `skill presence`.
+ *
+ * WHY THIS CALL. `npm i -g peaks-loop@<newer>` upgrades the CLI and leaves the
+ * project's generated config exactly as the OLD release wrote it:
+ * `initWorkspace` is the only writer and `ensureSession` early-returns once a
+ * session is bound, so nothing re-runs the generator. `.claude/settings.local.json`
+ * is drift-checked — but only on an init that never comes. The user found the
+ * previous instance of this by deleting their `.claude/*.json` and restarting;
+ * nothing in the product told them to.
+ *
+ * `peaks skill presence` is the ONE peaks call every skill makes in every turn
+ * (CLAUDE.md mandates it at the start of every response), so it is the only
+ * channel guaranteed to carry a drift notice to the LLM that can act on it —
+ * the same reasoning as the loop-hygiene verdict attached one screen down. A
+ * rule that lives only in a SKILL.md body is compacted away; a warning that
+ * rides the per-turn tool output is not.
+ *
+ * The field is additive and present only when stale, so no existing consumer
+ * of the envelope changes shape. `null` projectRoot means the caller had no
+ * project to inspect — skipped, not assumed stale.
+ */
+export function generatedConfigNotice(projectRoot) {
+    if (projectRoot === undefined)
+        return { field: {}, warnings: [] };
+    const staleness = detectStaleGeneratedArtifacts(projectRoot);
+    if (!staleness.stale)
+        return { field: {}, warnings: [] };
+    const onDiskVersion = staleness.onDisk?.packageVersion ?? '(unstamped)';
+    return {
+        field: {
+            generatedArtifacts: {
+                stale: true,
+                reasons: staleness.reasons,
+                onDiskPackageVersion: staleness.onDisk?.packageVersion ?? null,
+                installedPackageVersion: staleness.expected.packageVersion
+            }
+        },
+        warnings: [
+            `Generated config at '${projectRoot}' was produced by peaks-loop ${onDiskVersion} ` +
+                `but ${staleness.expected.packageVersion} is installed (${staleness.reasons.join(', ')}). ` +
+                `Re-run \`peaks workspace init\` ` +
+                `to regenerate .claude/settings.local.json and the offline template copy.`
+        ]
+    };
+}

package/dist/cli/commands/core/skill-heartbeat-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerSkillHeartbeatCommands(skill: Command, io: ProgramIO): void;

package/dist/cli/commands/core/skill-heartbeat-commands.js

@@ -0,0 +1,50 @@
+import { getSkillPresence, touchSkillHeartbeat } from '../../../services/skills/skill-presence-service.js';
+import { detectPresenceMarker } from '../../../services/hooks/presence-marker-detector.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+const HEARTBEAT_DESCRIPTION = 'Show the heartbeat status of the active Peaks skill';
+const HEARTBEAT_TOUCH_DESCRIPTION = 'Update the heartbeat timestamp (called by the LLM each turn to confirm peaks skill context is alive)';
+const DETECT_MARKER_LOSS_DESCRIPTION = 'Detect whether the latest assistant message lost the Peaks-Loop status header while a peaks skill is still active (slice 028 detection primitive).';
+const DETECT_MARKER_LOSS_MESSAGE_HELP = 'latest assistant message text to scan (defaults to reading the most recent LLM response from the stdin pipe, or empty string when no pipe is attached)';
+function runSkillHeartbeat(options, io) {
+    const presence = getSkillPresence();
+    if (presence === null) {
+        printResult(io, ok('skill.heartbeat', { active: false, heartbeat: 'none' }), options.json);
+        return;
+    }
+    printResult(io, ok('skill.heartbeat', {
+        active: true,
+        skill: presence.skill,
+        gate: presence.gate ?? null,
+        lastHeartbeat: presence.lastHeartbeat ?? presence.setAt,
+        setAt: presence.setAt
+    }), options.json);
+}
+function runSkillHeartbeatTouch(options, io) {
+    const updated = touchSkillHeartbeat();
+    if (updated === null) {
+        printResult(io, ok('skill.heartbeat:touch', { active: false, heartbeat: 'none' }), options.json);
+        return;
+    }
+    printResult(io, ok('skill.heartbeat:touch', {
+        active: true,
+        skill: updated.skill,
+        lastHeartbeat: updated.lastHeartbeat
+    }), options.json);
+}
+function runSkillDetectMarkerLoss(options, io) {
+    const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const message = options.message ?? '';
+    const result = detectPresenceMarker({ project: projectRoot, latestAssistantMessage: message });
+    printResult(io, ok('skill.detect-marker-loss', result), options.json);
+}
+export function registerSkillHeartbeatCommands(skill, io) {
+    addJsonOption(skill.command('heartbeat').description(HEARTBEAT_DESCRIPTION)).action((options) => runSkillHeartbeat(options, io));
+    addJsonOption(skill.command('heartbeat:touch').description(HEARTBEAT_TOUCH_DESCRIPTION)).action((options) => runSkillHeartbeatTouch(options, io));
+    addJsonOption(skill
+        .command('detect-marker-loss')
+        .description(DETECT_MARKER_LOSS_DESCRIPTION)
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--message <text>', DETECT_MARKER_LOSS_MESSAGE_HELP)).action((options) => runSkillDetectMarkerLoss(options, io));
+}

package/dist/cli/commands/core/skill-presence-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerSkillPresenceCommands(skill: Command, io: ProgramIO): void;

package/dist/cli/commands/core/skill-presence-commands.js

@@ -0,0 +1,123 @@
+import { setSkillPresence, getSkillPresence, isSkillPresenceMode, checkStalePresence } from '../../../services/skills/skill-presence-service.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { getSessionId, setSessionMeta } from '../../../services/session/session-manager.js';
+import { resolveCallerProjection } from '../../../services/session/resolve-caller-id.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+import { canonicalizeProjectOption, generatedConfigNotice } from './skill-generated-config-notice.js';
+import { contextVerdict } from './skill-context-verdict.js';
+const PRESENCE_DESCRIPTION = 'Show the currently active Peaks skill (alias: presence:get)';
+const PRESENCE_CHECK_STALE_HELP = 'slice 002 (v2.15.0): also report whether the recorded outer session id still matches the current one. Default false (back-compat).';
+const PRESENCE_PROJECT_HELP = 'project root (default: cwd)';
+const PRESENCE_SET_DESCRIPTION = 'Set the currently active Peaks skill for session-wide visibility. Slice 4.0.8: requires a bound session and an adapter-resolved caller id (fail-closed); raw unlink is rejected.';
+const PRESENCE_SET_MODE_HELP = 'execution mode';
+const PRESENCE_SET_GATE_HELP = 'current gate';
+const PRESENCE_SET_PROJECT_HELP = 'project root path (auto-detected from cwd when omitted)';
+function presenceActiveData(presence, parts) {
+    return {
+        active: true,
+        ...presence,
+        ...(parts.verdict.context !== null ? { context: parts.verdict.context } : {}),
+        ...parts.generatedConfig.field
+    };
+}
+function presenceStaleData(presence, staleness, parts) {
+    return {
+        active: true,
+        ...presence,
+        stale: staleness.stale,
+        staleReason: staleness.reason,
+        currentOuterSessionId: staleness.currentOuterSessionId,
+        recordedOuterSessionId: staleness.recordedOuterSessionId,
+        ...(parts.verdict.context !== null ? { context: parts.verdict.context } : {}),
+        ...parts.generatedConfig.field
+    };
+}
+function runSkillPresence(options, io) {
+    const projectOption = canonicalizeProjectOption(options.project);
+    const generatedConfig = generatedConfigNotice(projectOption ?? findProjectRoot(process.cwd()) ?? process.cwd());
+    const presence = getSkillPresence(projectOption);
+    if (presence === null) {
+        printResult(io, ok('skill.presence', { active: false, ...generatedConfig.field }, generatedConfig.warnings), options.json);
+        return;
+    }
+    // Loop-hygiene verdict: attached to every ACTIVE read, so the
+    // zero-pause contract travels with the one call every skill already
+    // makes — in every mode and every consumer project.
+    const verdict = contextVerdict(projectOption ?? process.cwd());
+    const parts = { verdict, generatedConfig };
+    // `--check-stale` lets callers (peaks-code Step 1, statusline) get both
+    // pieces of info from a single CLI invocation. The presence is returned
+    // UNCHANGED — it is a read-only flag, not a clear.
+    const data = options.checkStale === true
+        ? presenceStaleData(presence, checkStalePresence({ projectRootOverride: projectOption }), parts)
+        : presenceActiveData(presence, parts);
+    printResult(io, ok('skill.presence', data, generatedConfig.warnings, verdict.nextActions), options.json);
+}
+function printInvalidMode(io, options, name) {
+    printResult(io, fail('skill.presence:set', 'INVALID_MODE', `Invalid mode: ${options.mode} (expected one of: full-auto, assisted, strict, 24h)`, { name, mode: options.mode }, ['Use a valid mode: full-auto, assisted, strict, or 24h']), options.json);
+    process.exitCode = 1;
+}
+function printSessionNotBound(io, options, name, projectRoot) {
+    printResult(io, fail('skill.presence:set', 'PEAKS_SESSION_NOT_BOUND', 'No canonical peaks session is bound for this project (RD §3 D1).', { projectRoot, name }, ['Run `peaks workspace init --project <p>` first, then re-run `peaks skill presence:set`.']), options.json);
+    process.exitCode = 1;
+}
+function printCallerNotResolved(io, options, target, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    printResult(io, fail('skill.presence:set', 'PEAKS_CALLER_NOT_RESOLVED', `Active IDE adapter could not resolve a callerId (RD §3 D1): ${message}`, target, [
+        'Ensure the active IDE is detected by `peaks` and the IDE session variable is set.',
+        'Or set PEAKS_CALLER_ID=<id> in the environment for scripted usage.'
+    ]), options.json);
+    process.exitCode = 1;
+}
+function runSkillPresenceSet(name, options, io) {
+    const projectOption = canonicalizeProjectOption(options.project);
+    const projectRoot = projectOption ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    if (options.mode !== undefined && !isSkillPresenceMode(options.mode)) {
+        printInvalidMode(io, options, name);
+        return;
+    }
+    // Slice 4.0.8 (D1 + D2): `presence:set` is fail-closed. We refuse
+    // any write when (a) no peaks session is bound, or (b) the active
+    // IDE adapter cannot resolve a valid callerId. Both failures
+    // surface BEFORE any filesystem write. The legacy
+    // `setSkillPresence` wrapper is kept as a compat shim for tests
+    // and CLI flows that intentionally do not need a session — but
+    // production CLI traffic must go through this gate.
+    const boundSessionId = getSessionId(projectRoot);
+    if (boundSessionId === null) {
+        printSessionNotBound(io, options, name, projectRoot);
+        return;
+    }
+    try {
+        resolveCallerProjection({ projectRoot });
+    }
+    catch (err) {
+        printCallerNotResolved(io, options, { name, projectRoot }, err);
+        return;
+    }
+    const presence = setSkillPresence(name, options.mode, options.gate, projectOption);
+    // Session metadata is updated when a session is bound (read-only
+    // path: `getSessionId`). We do not auto-spawn a session.
+    if (boundSessionId !== null) {
+        setSessionMeta(projectRoot, boundSessionId, {
+            skill: name,
+            ...(options.mode ? { mode: options.mode } : {}),
+            ...(options.gate ? { gate: options.gate } : {})
+        });
+    }
+    printResult(io, ok('skill.presence:set', { active: true, ...presence }), options.json);
+}
+export function registerSkillPresenceCommands(skill, io) {
+    addJsonOption(skill
+        .command('presence')
+        .description(PRESENCE_DESCRIPTION)
+        .option('--check-stale', PRESENCE_CHECK_STALE_HELP)
+        .option('--project <path>', PRESENCE_PROJECT_HELP)).action((options) => runSkillPresence(options, io));
+    addJsonOption(skill
+        .command('presence:set <name>')
+        .description(PRESENCE_SET_DESCRIPTION)
+        .option('--mode <mode>', PRESENCE_SET_MODE_HELP)
+        .option('--gate <gate>', PRESENCE_SET_GATE_HELP)
+        .option('--project <path>', PRESENCE_SET_PROJECT_HELP)).action((name, options) => runSkillPresenceSet(name, options, io));
+}

package/dist/cli/commands/core/skill-presence-housekeeping-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerSkillPresenceHousekeepingCommands(skill: Command, io: ProgramIO): void;

package/dist/cli/commands/core/skill-presence-housekeeping-commands.js

@@ -0,0 +1,165 @@
+import { clearSkillPresence, getSkillPresence, checkStalePresence } from '../../../services/skills/skill-presence-service.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { generateProjectContext } from '../../../services/memory/project-context-service.js';
+import { gcStalePresenceLeases } from '../../../services/skills/presence-lease-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+const PRESENCE_CLEAR_DESCRIPTION = 'Unlink the DEPRECATED pre-4.0.11 single-slot presence marker files (`.peaks/_runtime/active-skill.json`, `.peaks/.active-skill.json`). It does NOT terminalize a live presence lease — a workflow-bound lease terminalizes through `peaks workflow terminalize --workflow <id> --reason <reason>`, an ad-hoc lease only at session exit, and raw unlink is FORBIDDEN for both. The envelope reports what is still active.';
+const PRESENCE_CLEAR_PROJECT_HELP = 'project root path (auto-detected from cwd when omitted)';
+const LEASE_GC_DESCRIPTION = 'Manually sweep stale presence leases for the canonical project. Both predicates required: now - lastHeartbeat > 1h AND now - startedAt > 24h. Drained leases are classified; corrupt graphs surface as PEAKS_GRAPH_REF_BROKEN warnings and are excluded.';
+const LEASE_GC_PROJECT_HELP = 'project root (default: cwd)';
+const LEASE_GC_NOW_HELP = 'override the current time (test seam)';
+const PRESENCE_CHECK_STALE_DESCRIPTION = 'Slice 002 (v2.15.0) AC-1: report whether the recorded presence outer session id still matches the current outer session id. ' +
+    'Returns { stale: boolean, reason: "outer-session-mismatch" | "no-presence" | null }. ' +
+    'Pure read-only — does NOT clear the presence (use `peaks skill presence:clear` for that).';
+const PRESENCE_CHECK_STALE_PROJECT_HELP = 'project root (default: cwd)';
+const PRESENCE_CHECK_STALE_CURRENT_OUTER_HELP = 'override the current outer session id (test seam; default: read from PEAKS_OUTER_SESSION_ID / CLAUDE_CODE_SESSION_ID)';
+const PRESENCE_CLEAR_SURVIVOR_ACTIONS = [
+    'A workflow-bound lease terminalizes through `peaks workflow terminalize --workflow <id> --reason <reason>`.',
+    'An ad-hoc lease (`peaks skill presence:set`) is terminalizable only at session exit; `presence:clear` will not remove it, and raw unlink is FORBIDDEN.',
+    'Run `peaks skill presence --json` to read the lease that survived.'
+];
+const LEASE_GC_NEXT_ACTIONS = [
+    'GC predicate: now - lastHeartbeat > 1h AND now - startedAt > 24h (RD §3 D2 + D3).',
+    'Re-run `peaks workspace init` or `peaks skill presence:set` to sweep the same project on the bound trigger.'
+];
+function presenceClearData(active, removed, cleared) {
+    return {
+        active,
+        removed,
+        cleared,
+        ...(cleared ? {} : { reason: 'live-lease-survives-presence-clear' }),
+        projectContextUpdated: true
+    };
+}
+async function runPresenceClear(options, io) {
+    const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    // What this command actually is: a stale-marker cleanup for projects
+    // carrying a pre-4.0.11 single-slot file, and nothing more. The previous
+    // description claimed it "routes workflow leases through `workflow
+    // terminalize`" and that a "compat wrapper re-routes [it] to
+    // `terminalizePresenceLease` when a workflow binding is present" — there is
+    // no such wrapper, and no such routing happens here or in
+    // `clearSkillPresence`. A caller who read that line and ran this command
+    // expecting a live workflow lease to terminalize got a successful exit code
+    // and a still-running lease.
+    const removed = clearSkillPresence(options.project);
+    // Auto-update project context so future sessions have up-to-date history.
+    // bootstraps `.peaks/project-scan/` (idempotent). Await the async
+    // signature; failure is still non-fatal so we don't block the clear.
+    try {
+        await generateProjectContext(projectRoot);
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // non-fatal: context update failure should not block presence clear
+    }
+    // Report the state the project is actually in, not the state this command
+    // intended to reach. `clearSkillPresence` unlinks only the DEPRECATED
+    // single-slot marker files; the canonical sid-scoped lease is deliberately
+    // left alive for an AD-HOC lease (raw unlink is FORBIDDEN — only session
+    // exit may terminalize one; workflow leases route through `workflow
+    // terminalize`). So after a `presence:set` the very next `peaks skill
+    // presence` call still reads `active: true`. A hardcoded `active: false`
+    // therefore reported a state the command never reached, and the caller had
+    // no way to tell that from a real clear.
+    //
+    // Re-reading through `getSkillPresence` — the same projection the
+    // `skill presence` command serves — is the only derivation that cannot
+    // drift from what the next command prints: it is the same read path, on
+    // the same project root, evaluated after every write this command makes.
+    const active = getSkillPresence(projectRoot) !== null;
+    // `cleared` is the live question the caller is actually asking ("is it gone
+    // now?"), which `removed` could never answer: a legacy marker being unlinked
+    // says nothing about the lease the next command will read. When it is false
+    // the envelope says WHY, in the two routes that can terminalize a lease —
+    // without this the caller saw `active: true, removed: false` and had no way
+    // to tell "you ran the wrong command" from "this command has no opinion".
+    const cleared = !active;
+    printResult(io, ok('skill.presence:clear', presenceClearData(active, removed, cleared), [], cleared ? [] : PRESENCE_CLEAR_SURVIVOR_ACTIONS), options.json);
+}
+function leaseGcData(result) {
+    return {
+        envelopeVersion: '4.0.8',
+        removed: result.removed,
+        retained: result.retained,
+        trigger: result.trigger,
+        inFlightBatch: result.inFlightBatch,
+        warnings: result.warnings,
+        errors: result.errors
+    };
+}
+// Slice 4.0.8 (RD §4): manual lease GC primitive. LLM-coordinated;
+// never a user-typed requirement. The user / LLM runner invokes
+// `peaks skill lease gc --project <p>` to drain leases that meet
+// both stale predicates (24h start AND 1h heartbeat) for the
+// canonical project. Returns a typed envelope so the runner can
+// branch on the aggregate counters.
+// Note: `.command('lease gc')` implicitly creates the `lease`
+// parent under `skill`; we MUST NOT also call `.command('lease')`
+// separately, or Commander.js throws "cannot add command 'lease' as
+// already have command 'lease'" at startup.
+async function runLeaseGc(options, io) {
+    const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    try {
+        const result = await gcStalePresenceLeases({
+            projectRoot,
+            ...(options.now !== undefined ? { now: options.now } : {}),
+            trigger: 'manual'
+        });
+        printResult(io, ok('skill.lease.gc', leaseGcData(result), result.warnings.map((w) => `${w.code}: ${w.message}`), LEASE_GC_NEXT_ACTIONS), options.json);
+    }
+    catch (err) {
+        printResult(io, fail('skill.lease.gc', 'PEAKS_LEASE_GC_FAILED', getErrorMessage(err), { projectRoot }, [
+            'Re-run with a valid --project and ensure the session is bound.'
+        ]), options.json);
+        process.exitCode = 1;
+    }
+}
+// peaks-code Step 1 (and `peaks code should-pause --step
+// step-1-mode-select`) calls this to decide whether the recorded
+// `mode` field can be trusted or whether the LLM must AskUserQuestion.
+function runPresenceCheckStale(options, io) {
+    // when the user omits the flag. The service-layer branch
+    // `'currentOuter' in opts` returns true for an explicit
+    // `undefined` (the key exists on the spread object literal),
+    // which would skip the env-var fallback and pin `current =
+    // undefined` — always reading the presence as stale. Build a
+    // sparse opts object so the service can fall back to
+    // `getCurrentOuterSessionId()` (reads PEAKS_OUTER_SESSION_ID /
+    // CLAUDE_CODE_SESSION_ID).
+    const checkOpts = options.project !== undefined ? { projectRootOverride: options.project } : {};
+    if (options.currentOuter !== undefined) {
+        checkOpts.currentOuter = options.currentOuter;
+    }
+    const result = checkStalePresence(checkOpts);
+    // Always emit `currentOuterSessionId` in the JSON envelope (even
+    // tooling (statusline, sub-agent dispatch) reads the field by
+    // name, never by `data.currentOuterSessionId ?? ''`. JSON.stringify
+    // drops `undefined` properties, so we coerce to '' before
+    // wrapping in the envelope.
+    const data = {
+        stale: result.stale,
+        reason: result.reason,
+        presence: result.presence,
+        currentOuterSessionId: result.currentOuterSessionId ?? '',
+        recordedOuterSessionId: result.recordedOuterSessionId ?? ''
+    };
+    printResult(io, ok('skill.presence:check-stale', data), options.json);
+}
+export function registerSkillPresenceHousekeepingCommands(skill, io) {
+    addJsonOption(skill
+        .command('presence:clear')
+        .description(PRESENCE_CLEAR_DESCRIPTION)
+        .option('--project <path>', PRESENCE_CLEAR_PROJECT_HELP)).action((options) => runPresenceClear(options, io));
+    addJsonOption(skill
+        .command('lease gc')
+        .description(LEASE_GC_DESCRIPTION)
+        .option('--project <path>', LEASE_GC_PROJECT_HELP)
+        .option('--now <iso>', LEASE_GC_NOW_HELP)).action((options) => runLeaseGc(options, io));
+    addJsonOption(skill
+        .command('presence:check-stale')
+        .description(PRESENCE_CHECK_STALE_DESCRIPTION)
+        .option('--project <path>', PRESENCE_CHECK_STALE_PROJECT_HELP)
+        .option('--current-outer <id>', PRESENCE_CHECK_STALE_CURRENT_OUTER_HELP)).action((options) => runPresenceCheckStale(options, io));
+}

package/dist/cli/commands/core/skill-registry-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerSkillRegistryCommands(skill: Command, io: ProgramIO): void;

package/dist/cli/commands/core/skill-registry-commands.js

@@ -0,0 +1,117 @@
+import { runDoctor } from '../../../services/doctor/index.js';
+import { listSkills } from '../../../services/skills/skill-registry.js';
+import { runSkillSync, SYNC_PLATFORMS } from '../../../services/skills/sync-service.js';
+import { ok, fail } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+const PLATFORM_IDS = SYNC_PLATFORMS.join(', ');
+const LIST_DESCRIPTION = 'List skills derived from skills/*/SKILL.md';
+const LIST_INCLUDE_INTERNAL_HELP = 'include skills with visibility: internal (default: hide them)';
+const DOCTOR_DESCRIPTION = 'Run skill-related doctor checks';
+const SYNC_DESCRIPTION = `Sync the peaks-* skill family to one or all of the 8 supported LLM-CLI platforms (${PLATFORM_IDS}). Idempotent.`;
+const SYNC_PLATFORM_HELP = `sync only one platform (default: --all). Valid: ${PLATFORM_IDS}`;
+const SYNC_ALL_HELP = 'sync all 8 platforms (default if --platform is omitted)';
+const SYNC_DRY_RUN_HELP = 'do not write; emit the same shape with applied=false';
+const SYNC_RECONCILE_HELP = 'repair Peaks-managed skill Junctions whose targets were deleted with a host worktree';
+const SYNC_PROJECT_HELP = 'project root (default: cwd)';
+function sortSkillsForDisplay(skills) {
+    return [...skills].sort((a, b) => {
+        // door) — list it FIRST so users discover the dispatcher before
+        // any specific leaf. Followed by peaks-sop (current default
+        // runbook showcase) and peaks-code (canonical code-domain
+        // orchestrator); everything else falls back to alphabetical.
+        if (a.name === 'peaks-solo')
+            return -1;
+        if (b.name === 'peaks-solo')
+            return 1;
+        if (a.name === 'peaks-sop')
+            return -1;
+        if (b.name === 'peaks-sop')
+            return 1;
+        if (a.name === 'peaks-code')
+            return -1;
+        if (b.name === 'peaks-code')
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+}
+function runSkillList(options, io) {
+    return listSkills().then((all) => {
+        const skills = options.includeInternal === true ? all : all.filter((s) => s.visibility !== 'internal');
+        if (options.json === true) {
+            printResult(io, ok('skill.list', { skills }), true);
+            return;
+        }
+        for (const skill of sortSkillsForDisplay(skills)) {
+            io.stdout(`  ${skill.name.padEnd(14)}${skill.description}`);
+        }
+        io.stdout(`\n  Invoke any skill by typing its name in conversation (e.g. \`peaks-sop\`).`);
+    });
+}
+function runSkillDoctor(options, io) {
+    return runDoctor().then((report) => {
+        const skillChecks = report.checks.filter((check) => check.id.startsWith('skill'));
+        const failed = skillChecks.filter((check) => !check.ok).length;
+        if (options.json === true) {
+            printResult(io, ok('skill.doctor', { checks: skillChecks, ok: failed === 0 }), true);
+        }
+        else {
+            for (const check of skillChecks) {
+                const icon = check.ok ? '+' : '×';
+                io.stdout(`  ${icon}  ${check.message}`);
+            }
+            io.stdout(`\n  ${skillChecks.length - failed} passed, ${failed} failed`);
+            if (failed > 0) {
+                io.stderr('\nOne or more skill checks failed.');
+            }
+        }
+        if (failed > 0) {
+            process.exitCode = 1;
+        }
+    });
+}
+async function runSkillSyncCommand(options, io) {
+    try {
+        const projectRoot = options.project ?? process.cwd();
+        const platforms = options.platform !== undefined ? [options.platform] : undefined;
+        const result = await runSkillSync({
+            projectRoot,
+            ...(platforms !== undefined ? { platforms } : {}),
+            ...(options.dryRun === true ? { dryRun: true } : {}),
+            ...(options.reconcileJunctions === true ? { reconcileJunctions: true } : {})
+        });
+        const envelope = ok('skill.sync', result, [], [
+            `syncedCount: ${result.syncedCount}/${result.perPlatform.length} platforms`,
+            `totalInstalled: ${result.totalInstalled} skill symlinks`,
+            result.failedCount > 0
+                ? `failedCount: ${result.failedCount} (run \`peaks skill status\` for details)`
+                : 'no failures'
+        ]);
+        printResult(io, envelope, options.json);
+        if (result.failedCount > 0) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        printResult(io, fail('skill.sync', 'SKILL_SYNC_FAILED', message, { applied: false }, [message]), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerSkillRegistryCommands(skill, io) {
+    addJsonOption(skill
+        .command('list')
+        .description(LIST_DESCRIPTION)
+        .option('--include-internal', LIST_INCLUDE_INTERNAL_HELP)).action((options) => runSkillList(options, io));
+    addJsonOption(skill.command('doctor').description(DOCTOR_DESCRIPTION)).action((options) => runSkillDoctor(options, io));
+    // Slice #12 final piece (per spec §9 line 1105):
+    // `peaks skills sync 8 平台分发`. Idempotent: re-running is a
+    // no-op when the symlinks are already correct.
+    addJsonOption(skill
+        .command('sync')
+        .description(SYNC_DESCRIPTION)
+        .option('--platform <id>', SYNC_PLATFORM_HELP)
+        .option('--all', SYNC_ALL_HELP)
+        .option('--dry-run', SYNC_DRY_RUN_HELP)
+        .option('--reconcile-junctions', SYNC_RECONCILE_HELP)
+        .option('--project <path>', SYNC_PROJECT_HELP)).action((options) => runSkillSyncCommand(options, io));
+}

package/dist/cli/commands/core/skill-runbook-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerSkillRunbookCommand(skill: Command, io: ProgramIO): void;

package/dist/cli/commands/core/skill-runbook-command.js

@@ -0,0 +1,29 @@
+import { inspectSkillRunbook } from '../../../services/skills/skill-runbook-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+export function registerSkillRunbookCommand(skill, io) {
+    addJsonOption(skill
+        .command('runbook <name>')
+        .description('Inspect a skill Default runbook section and its --apply authorization-note status')).action(async (name, options) => {
+        try {
+            const inspection = await inspectSkillRunbook(name);
+            const result = inspection.ok
+                ? ok('skill.runbook', inspection)
+                : fail('skill.runbook', inspection.hasRunbook ? 'SKILL_RUNBOOK_APPLY_UNGATED' : 'SKILL_RUNBOOK_MISSING', inspection.hasRunbook
+                    ? `Skill ${inspection.name} has ${inspection.destructiveApplyLines.length} destructive --apply command(s) without an authorization/dry-run note`
+                    : `Skill ${inspection.name} is missing a ## Default runbook section`, inspection, inspection.hasRunbook
+                    ? [
+                        'Add an authorization or --dry-run note next to destructive --apply lines in the runbook section'
+                    ]
+                    : ['Add a `## Default runbook` section to the skill SKILL.md']);
+            printResult(io, result, options.json);
+            if (!inspection.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('skill.runbook', 'SKILL_NOT_FOUND', getErrorMessage(error), { name }), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/dispatch-command-spec.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function buildDispatchCommandSpec(parent: Command): Command;