peaks-loop 4.0.0-beta.9 → 4.0.3

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

@@ -0,0 +1,221 @@
+/**
+ * `peaks container spawn | release` — slice 2026-07-29-worktree-l2-extended Part 12.
+ *
+ * L4 container isolation bridge: Part 8 landed the CLI contract
+ * (`peaks sub-agent dispatch --isolation container` is accepted
+ * and fail-fasts with ISOLATION_CONTAINER_NOT_YET_IMPLEMENTED).
+ * Part 12 implements the spawn/release CLI surface so the
+ * dispatch command can shell out to it.
+ *
+ * This file is the `peaks container` parent command. Sub-commands:
+ *   - spawn   : `docker run <image> ...` + write container lease
+ *   - release : `docker rm --force <id>` + transition lease to released
+ *
+ * Runtime requirement: `docker` CLI on PATH. The spawn checks
+ * `docker --version` first and returns CONTAINER_RUNTIME_UNAVAILABLE
+ * with a remediation hint when the daemon is not running. Windows
+ * is supported if Docker Desktop / WSL2 is installed; native podman
+ * is a follow-up (the container-lease module is runtime-agnostic).
+ *
+ * Lease is the source of truth: the dispatch record (v3) carries
+ * the leaseId; the PreToolUse gate (Part 2.B pattern) will read
+ * PEAKS_CONTAINER_LEASE_ID and consult the lease file before
+ * allowing docker-related tool calls. The gate bridge is a
+ * follow-up rid.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { containerLeaseFilePath, deserializeContainerLease, finalizeContainerLease, generateContainerLeaseId, markContainerReleased, ttlForContainerRole } from '../../services/container/container-lease.js';
+const DEFAULT_DOCKER_IMAGE = 'node:22-slim';
+function detectContainerRuntime(explicit) {
+    const tryOrder = explicit ? [explicit] : ['docker', 'podman'];
+    for (const r of tryOrder) {
+        try {
+            const version = execSync(`${r} --version`, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }).trim();
+            return { ok: true, runtime: r, binary: `${r} (${version.split('\n')[0] ?? ''})` };
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return {
+        ok: false,
+        stderr: explicit
+            ? `explicit --runtime ${explicit} not on PATH`
+            : 'neither docker nor podman is on PATH',
+        hint: explicit
+            ? `Install ${explicit} or pass a different --runtime.`
+            : 'Install docker (Docker Desktop on macOS / Windows) or podman (RHEL / Fedora).'
+    };
+}
+function joinPathSession(projectRoot, sessionId) {
+    return `${projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${sessionId}`;
+}
+function checkDockerAvailable() {
+    // Part 43: superseded by detectContainerRuntime above; this
+    // function is preserved for callers that imported it. The
+    // container-commands.ts action handlers all use
+    // detectContainerRuntime directly.
+    return { ok: false, stderr: 'deprecated — use detectContainerRuntime' };
+}
+export function registerContainerCommand(program, io) {
+    const cmd = program.command('container').description('L4 container isolation: spawn/release container leases (Part 12; pairs with --isolation container on dispatch).');
+    addJsonOption(cmd.command('spawn')
+        .description('Spawn a container via `docker run` and write a container lease. ' +
+        'The lease is the source of truth for the L4 PreToolUse gate (Part 12 follow-up). ' +
+        'Default TTL is role-aware (rd=30m / qa=15m / ui=1h); pass --ttl <ms> to override. ' +
+        'Default image is `node:22-slim`; pass --image <name> to override.')
+        .requiredOption('--rid <rid>', 'peaks request id the lease is associated with')
+        .requiredOption('--role <role>', 'sub-agent role (rd | qa | ui | sc | prd | general-purpose)')
+        .requiredOption('--purpose <text>', 'why this container was spawned (audit log)')
+        .option('--image <name>', `container image (default ${DEFAULT_DOCKER_IMAGE})`)
+        .option('--ttl <ms>', 'time-to-live in ms (default role-aware; override with positive number)')
+        .option('--mount <path>', 'host path to mount as the container working dir (default: <projectRoot>)')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action(async (options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = options.session ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        try {
+            const explicitRuntime = (() => {
+                if (options.runtime === 'docker')
+                    return 'docker';
+                if (options.runtime === 'podman')
+                    return 'podman';
+                return undefined;
+            })();
+            const runtime = detectContainerRuntime(explicitRuntime);
+            if (!runtime.ok) {
+                printResult(io, fail('container.spawn', 'CONTAINER_RUNTIME_UNAVAILABLE', `${runtime.stderr}: ${runtime.hint}`, { rid: options.rid, role: options.role, sessionId }, [
+                    'Install docker (Docker Desktop on macOS / Windows) or podman (RHEL / Fedora).',
+                    'On Windows, ensure WSL2 backend is enabled and the daemon is running.',
+                    'Pass --runtime docker|podman to force a specific runtime.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const leaseId = generateContainerLeaseId();
+            const now = Date.now();
+            const ttlMs = options.ttl === undefined ? ttlForContainerRole(options.role) : Number.parseInt(options.ttl, 10);
+            if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
+                printResult(io, fail('container.spawn', 'INVALID_TTL', '--ttl must be a positive integer (ms)', { ttl: options.ttl }, ['Re-run with --ttl 1800000 (30 min) or omit to use role default.']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const image = options.image ?? DEFAULT_DOCKER_IMAGE;
+            const mount = options.mount ?? projectRoot;
+            // `docker run --rm -d` so the container is detached and
+            // auto-removed when stopped; --cidfile writes the
+            // container id to a file we can read back. The
+            // `--label peaks.leaseId=<id>` lets `peaks container
+            // list` / `peaks container gc` find orphans by label
+            // when the lease file is missing.
+            const cidFile = `${joinPathSession(projectRoot, sessionId).replace(/\\/g, '/')}/.${runtime.runtime}-cid-${leaseId}`;
+            try {
+                execSync(`${runtime.runtime} run --rm -d --cidfile "${cidFile}" --label "peaks.leaseId=${leaseId}" --label "peaks.rid=${options.rid}" -v "${mount}:/work" -w /work ${image} sleep infinity`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+            }
+            catch (err) {
+                printResult(io, fail('container.spawn', 'DOCKER_RUN_FAILED', getErrorMessage(err), { rid: options.rid, image, runtime: runtime.runtime, sessionId }, [
+                    'Verify the image name is reachable on the configured registry.',
+                    'Verify the host path is mounted correctly (Windows: the path must be visible to WSL2).',
+                    `Run \`${runtime.runtime} ps -a\` to inspect any leftover containers with the peaks.leaseId label.`
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const containerId = readFileSync(cidFile, 'utf8').trim();
+            const lease = finalizeContainerLease({
+                leaseId,
+                rid: options.rid,
+                role: options.role,
+                path: mount,
+                image,
+                containerId,
+                createdAt: now,
+                expiresAt: now + ttlMs,
+                purpose: options.purpose
+            });
+            atomicWriteJson(containerLeaseFilePath(joinPathSession(projectRoot, sessionId), leaseId), lease);
+            printResult(io, ok('container.spawn', {
+                lease,
+                sessionId,
+                projectRoot,
+                runtime: runtime.runtime,
+                runtimeVersion: runtime.binary,
+                nextActions: [
+                    `Container id: ${containerId}`,
+                    `Image: ${image}`,
+                    `Lease expires at: ${new Date(lease.expiresAt).toISOString()}`,
+                    'Run `peaks container release --lease-id <id>` when done'
+                ]
+            }, [], []), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('container.spawn', 'SPAWN_FAILED', getErrorMessage(err), { rid: options.rid, sessionId }, [
+                'See error message; if the lease was not written, retry after fixing the underlying issue.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('release')
+        .description('Transition a container lease to released and run `docker rm --force`. Idempotent on already-released leases.')
+        .requiredOption('--lease-id <id>', 'lease id returned by `peaks container spawn`')
+        .option('--session <sid>', 'override session id')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = options.session ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        try {
+            const file = containerLeaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+            if (!existsSync(file)) {
+                printResult(io, fail('container.release', 'LEASE_NOT_FOUND', `no lease on disk at ${file}`, { leaseId: options.leaseId, file }, [
+                    'Run `peaks container list` to inspect active leases.',
+                    'For a never-spawned lease, this is a no-op — no further action needed.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let lease;
+            try {
+                lease = deserializeContainerLease(readFileSync(file, 'utf8'));
+            }
+            catch (err) {
+                printResult(io, fail('container.release', 'LEASE_FILE_INVALID', getErrorMessage(err), { leaseId: options.leaseId, file }, [
+                    'Delete the malformed lease file manually and re-issue spawn.',
+                    'For security, release never fails open on a malformed lease.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (lease.status === 'released') {
+                printResult(io, ok('container.release', { lease, sessionId, projectRoot, alreadyReleased: true }, [], [`Lease ${lease.leaseId} already released; nothing to do.`]), options.json);
+                return;
+            }
+            let dockerRmFailed = false;
+            try {
+                const releaseRuntime = detectContainerRuntime(undefined);
+                const runtimeCmd = releaseRuntime.ok ? releaseRuntime.runtime : 'docker';
+                execSync(`${runtimeCmd} rm --force "${lease.containerId}"`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' });
+            }
+            catch {
+                dockerRmFailed = true;
+            }
+            const released = markContainerReleased(lease);
+            atomicWriteJson(file, released);
+            printResult(io, ok('container.release', { lease: released, sessionId, projectRoot, dockerRmFailed }, dockerRmFailed ? ['docker rm failed (likely the container was already removed); lease marked released.'] : [], [
+                `Lease ${lease.leaseId} marked released.`,
+                dockerRmFailed ? 'Manual `docker ps -a` + `docker rm` may be needed.' : `Container ${lease.containerId} removed.`
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('container.release', 'RELEASE_FAILED', getErrorMessage(err), { leaseId: options.leaseId, sessionId }, [
+                'Verify the lease id and re-run.',
+                'If the lease was never spawned, no-op.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -19,11 +19,12 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { searchMemory } from '../../services/memory/memory-search-service.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { getSessionIdCanonical } from '../../services/session/session-manager.js';
-import { evaluateMainSessionThreshold, pickMainSessionTrigger, formatMainSessionTriggerLogLine, detectIdeFromEnv } from '../../services/context/main-session-monitor.js';
+import { evaluateMainSessionThreshold, pickMainSessionTrigger, formatMainSessionTriggerLogLine } from '../../services/context/main-session-monitor.js';
+import { detectIdeFromEnv } from '../../services/context/ide-detect.js';
 const SKILLS_DIR = 'skills';
 function readSkillsDir(projectRoot) {
     const skillsRoot = join(projectRoot, SKILLS_DIR);

package/dist/cli/commands/core/artifacts-command.js

@@ -1,6 +1,6 @@
 import { createArtifactInitPlan, getArtifactStatus, createGuidedArtifactSetup } from '../../../services/artifacts/artifact-service.js';
 import { getArtifactWorkspaceStatus, planArtifactSync } from '../../../services/artifacts/workspace-service.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, failUnsupportedNonDryRun, isArtifactProvider, isArtifactSetupStep, printResult } from '../../cli-helpers.js';
 export function registerArtifactsCommand(program, io) {
     const artifacts = program.command('artifacts').description('Manage intermediate artifact repositories');

package/dist/cli/commands/core/binding-commands.js

@@ -1,7 +1,7 @@
 import { addJsonOption, printResult } from '../../cli-helpers.js';
 import { findProjectRoot } from '../../../services/config/config-safety.js';
 import { loadBindingStatus, formatTable, formatJson } from '../../../services/session/binding-status-service.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 // v2.18.2 PATCH scope (follow-up issues #2). Read-only introspection
 // CLI. Surface is intentionally minimal: one subcommand
 // (`peaks binding status`), two output modes (table + json), one

package/dist/cli/commands/core/doctor-command.js

@@ -1,8 +1,62 @@
-import { runDoctor } from '../../../services/doctor/doctor-service.js';
+import { runDoctor } from '../../../services/doctor/index.js';
 import { readBinding, dropStale, rebuildBindingFromLegacy } from '../../../services/session/binding-store.js';
 import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { loadSkillRegistry } from '../../../services/skills/skill-registry.js';
+import { planStatusLineInstall } from '../../../services/skills/statusline-settings-service.js';
 import { addJsonOption, printResult } from '../../cli-helpers.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+// slice-3b Option C: the doctor subpackage owns the check pipeline but
+// does NOT import cross-domain utils from the main package (avoids
+// circular deps). The CLI is the natural wiring point — every cross-
+// domain util the doctor used to import directly is now injected as a
+// probe on DoctorOptions at call-site:
+//
+//   loadSkills           ← loadSkillRegistry (main/services/skills/skill-registry.ts)
+//   skillPresenceProbe   ← leave as-is; doctor-command does not own the presence probe
+//   statusLineInstalledProbe ← defaults to a `planStatusLineInstall` wrapper below
+//   projectRootResolver  ← findProjectRoot (main/services/config/config-safety.ts)
+//   isValidSessionIdProbe ← the regex kept in main/services/workspace/sid-naming-guard.ts
+//
+// Inlining isValidSessionId via the doctor subpackage's default regex
+// (which mirrors the upstream file byte-for-byte) keeps the L3 orphan
+// check behaviour-identical without dragging sid-naming-guard into a
+// workspace package. If sid-naming-guard is ever moved into
+// peaks-loop-shared, swap this for a re-import.
+function doctorIsValidSessionId(sid) {
+    return /^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])-session-[0-9a-z]{3,6}$/.test(sid);
+}
+function statusLineAlreadyInstalledForScope(scope, projectRoot) {
+    try {
+        if (scope === 'project') {
+            if (projectRoot === undefined)
+                return false;
+            return planStatusLineInstall('project', projectRoot).alreadyInstalled;
+        }
+        return planStatusLineInstall('global').alreadyInstalled;
+    }
+    catch {
+        return false;
+    }
+}
+function doctorStatusLineInstalledProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    // Check both scopes: a user may have installed the statusLine globally, which
+    // the project-only check would miss and falsely report as "not installed".
+    try {
+        if (projectRoot !== null && statusLineAlreadyInstalledForScope('project', projectRoot)) {
+            return true;
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* fall through to global */
+    }
+    try {
+        return statusLineAlreadyInstalledForScope('global');
+    }
+    catch {
+        return false;
+    }
+}
 // Slice v2.16.0 AC-10: stale binding TTL is 5 minutes by default. The
 // threshold is exposed as a CLI flag so users can tune it for
 // long-running sessions.
@@ -129,7 +183,13 @@ export function registerDoctorCommand(program, io) {
             }
             return;
         }
-        const report = await runDoctor();
+        const report = await runDoctor({
+            // slice-3b Option C: wire cross-domain probes at call-site.
+            loadSkills: loadSkillRegistry,
+            projectRootResolver: () => findProjectRoot(process.cwd()),
+            isValidSessionIdProbe: doctorIsValidSessionId,
+            statusLineInstalledProbe: doctorStatusLineInstalledProbe
+        });
         let logsSection = null;
         if (options.log === true) {
             logsSection = await buildDoctorLogsSection();

package/dist/cli/commands/core/memory-command.js

@@ -1,5 +1,5 @@
 import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../../services/memory/project-memory-service.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 export function registerMemoryCommand(program, io) {
     const memory = program.command('memory').description('Manage project-local Peaks memory');

package/dist/cli/commands/core/profile-command.js

@@ -1,5 +1,5 @@
 import { listProfiles } from '../../../services/profiles/profile-service.js';
-import { ok } from '../../../shared/result.js';
+import { ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../../cli-helpers.js';
 export function registerProfileCommand(program, io) {
     const profile = program.command('profile').description('Manage runtime profiles');

package/dist/cli/commands/core/proxy-command.js

@@ -1,5 +1,5 @@
 import { planProxyTest } from '../../../services/proxy/proxy-service.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../../cli-helpers.js';
 export function registerProxyCommand(program, io) {
     const proxy = program.command('proxy').description('Manage proxy settings');

package/dist/cli/commands/core/session-command.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { getSessionMeta, rotateSessionBinding, setSessionTitle, listSessionMetas } from '../../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../../services/config/config-service.js';
 import { findProjectRoot } from '../../../services/config/config-safety.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 // Slice 2026-07-01-strategic-compact-cli fix: register the
 // `peaks session checkpoint` and `peaks session resume` subcommands
@@ -13,13 +13,17 @@ import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.j
 // saw them — they were effectively hidden.
 import { registerSessionCheckpointCommand } from '../session-checkpoint-command.js';
 import { registerSessionResumeCommand } from '../session-resume-command.js';
-import { registerSessionAutoCompactHookCommand } from '../session-auto-compact-hook-command.js';
 // Slice 2 of the peaks-code → peaks-code rename plan: register the
 // `peaks session migrate-skill-name` subcommand eagerly alongside
 // checkpoint / resume / auto-compact-hook so it appears in
 // `peaks session --help` for LLM `<TAB>`-discovery. See
 // src/services/migrate-skill-name/.
 import { registerSessionMigrateSkillNameCommand } from '../session-migrate-skill-name.js';
+// rid-020a: register `peaks session 24h-mode` eagerly so the
+// state-machine sub-actions (state / transition / attempts / reset)
+// appear in `peaks session --help` for LLM `<TAB>`-discovery.
+import { registerSession24hModeCommand } from '../session-24h-mode.js';
+import { registerSpillDemoCommand } from '../spill-demo-command.js';
 export function registerSessionCommand(program, io) {
     const session = program.command('session').description('Manage Peaks session directories');
     addJsonOption(session
@@ -193,17 +197,15 @@ export function registerSessionCommand(program, io) {
     // `<TAB>`-discovery and the LLM never saw them.
     registerSessionCheckpointCommand(session, io);
     registerSessionResumeCommand(session, io);
-    // Slice 2026-07-02-auto-compact-zero-pause: the Bash command the
-    // PreToolUse hook in `.claude/settings.local.json` fires. Keeping
-    // it eager (same fix as checkpoint + resume) so `peaks session --help`
-    // lists it for LLM `<TAB>`-discovery.
-    registerSessionAutoCompactHookCommand(session);
     // Slice 2 of the peaks-code → peaks-code rename plan:
     // `peaks session migrate-skill-name --from <old> --to <new>
     // [--apply] [--project <path>] [--json]`. Idempotent rewrite of
     // .peaks/_runtime/** for the rename; skipped paths recorded in
     // the response envelope. See src/services/migrate-skill-name/.
     registerSessionMigrateSkillNameCommand(session);
+    // rid-020a: peaks session 24h-mode — state machine backbone.
+    registerSession24hModeCommand(session, io);
+    registerSpillDemoCommand(session, io);
     addJsonOption(session
         .command('rotate')
         .description('Drop the project-level session binding so the next peaks call auto-generates a fresh session id. The on-disk session directory is left intact — only .peaks/.session.json is removed.')

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

@@ -1,4 +1,4 @@
-import { runDoctor } from '../../../services/doctor/doctor-service.js';
+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 { inspectSkillRunbook } from '../../../services/skills/skill-runbook-service.js';
@@ -7,7 +7,7 @@ import { detectPresenceMarker } from '../../../services/hooks/presence-marker-de
 import { findProjectRoot } from '../../../services/config/config-safety.js';
 import { generateProjectContext } from '../../../services/memory/project-context-service.js';
 import { getSessionId, setSessionMeta } from '../../../services/session/session-manager.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 // Slice S0 (4.0.0-beta.5 peaks-solo dispatcher release):
 // `peaks skill search` is the CLI primitive that feeds the
@@ -20,8 +20,11 @@ import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.j
 import { registerSkillSearchCommand } from '../skill-search-commands.js';
 export function registerSkillCommand(program, io) {
     const skill = program.command('skill').description('Manage Peaks skills');
-    addJsonOption(skill.command('list').description('List skills derived from skills/*/SKILL.md')).action(async (options) => {
-        const skills = await listSkills();
+    addJsonOption(skill.command('list').description('List skills derived from skills/*/SKILL.md').option('--include-internal', 'include skills with visibility: internal (default: hide them)')).action(async (options) => {
+        let skills = await listSkills();
+        if (options.includeInternal !== true) {
+            skills = skills.filter((s) => s.visibility !== 'internal');
+        }
         if (options.json === true) {
             printResult(io, ok('skill.list', { skills }), true);
         }

package/dist/cli/commands/core/standards-command.js

@@ -2,7 +2,7 @@ import { summarizeProjectStandardsInitResult, summarizeProjectStandardsUpdateRes
 import { executeProjectStandardsInitIdeAware, executeProjectStandardsUpdateIdeAware } from '../../../services/standards/ide-aware-standards-service.js';
 import { migrateStandards } from '../../../services/standards/migrate-service.js';
 import { migrateClaudeRules } from '../../../services/standards/migrate-claude-rules-service.js';
-import { fail, ok } from '../../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 export function registerStandardsCommand(program, io) {
     const standards = program.command('standards').description('Manage project-local coding standards');

package/dist/cli/commands/cron-commands.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `peaks cron` — slice 2026-07-29-worktree-l2-extended Part 14.
+ *
+ * Persistent scheduled-task system. Stores a JSON schedule at
+ * `.peaks/cron/schedule.json` and lets the LLM-side runner
+ * trigger tasks synchronously (`peaks cron run <id>`) or
+ * register a built-in periodic lease gc that the runbook
+ * (`skills/peaks-code/`) checks on every session start.
+ *
+ * Built-in tasks (the only ones auto-registered today):
+ *   - `lease-gc-daily` — runs `peaks worktree gc --all-sessions
+ *     --project .` once every 24h. Cleans up orphan leases that
+ *     leaked past their auto-release hook (Part 3.A) — the
+ *     safety net for the safety net.
+ *
+ * Why a JSON file (not a real cron daemon): peaks-loop is a CLI
+ * tool, not a service. The schedule is best-effort: the runbook
+ * checks it on session start and surfaces overdue tasks. A
+ * proper system cron / systemd timer is the production
+ * deployment story; this CLI is the portable fallback.
+ *
+ * File layout:
+ *   .peaks/cron/schedule.json — registered tasks with their
+ *     interval + lastRunAt
+ *   .peaks/cron/history.jsonl — append-only run history
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+declare const SCHEDULE_VERSION: 1;
+export type ScheduleEntry = {
+    readonly id: string;
+    readonly name: string;
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    readonly intervalMs: number;
+    readonly lastRunAt: number | null;
+    readonly enabled: boolean;
+    readonly createdAt: number;
+};
+export type ScheduleFile = {
+    readonly version: typeof SCHEDULE_VERSION;
+    readonly entries: ReadonlyArray<ScheduleEntry>;
+};
+export type RunRecord = {
+    readonly id: string;
+    readonly taskId: string;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly exitCode: number;
+    readonly stderr: string;
+};
+export declare function readSchedule(projectRoot: string): ScheduleFile;
+export declare function appendHistory(projectRoot: string, record: RunRecord): void;
+export declare function runTask(projectRoot: string, task: ScheduleEntry): RunRecord;
+export declare function listDueTasks(projectRoot: string, now?: number): ReadonlyArray<ScheduleEntry>;
+export declare function registerCronCommand(program: Command, io: ProgramIO): void;
+export {};