peaks-cli 1.2.8 → 1.3.0

package/dist/src/services/skills/skill-presence-service.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
 import { getSessionMeta } from '../session/session-manager.js';
@@ -31,8 +31,16 @@ function getCurrentOuterSessionId() {
         return claude;
     return undefined;
 }
-const PRESENCE_FILE = '.peaks/.active-skill.json';
-const SESSION_FILE = '.peaks/.session.json';
+// As of slice 2026-06-05-peaks-runtime-layer the orchestrator's
+// active-skill marker lives under `.peaks/_runtime/active-skill.json`.
+// The legacy `.peaks/.active-skill.json` path is preserved as a
+// read-only fallback for one minor release so older CLI versions (or
+// trees that have not been migrated by `peaks workspace reconcile`)
+// keep working without a forced re-init.
+const PRESENCE_FILE = join('.peaks', '_runtime', 'active-skill.json');
+const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
+const SESSION_FILE = join('.peaks', '_runtime', 'session.json');
+const SESSION_FILE_LEGACY = '.peaks/.session.json';
 function resolveProjectRoot(override) {
     if (override)
         return resolve(override);
@@ -41,12 +49,44 @@ function resolveProjectRoot(override) {
 function resolvePresencePath(projectRootOverride) {
     return resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE);
 }
+/**
+ * Back-compat read for the active-skill marker. Prefers the new
+ * canonical `.peaks/_runtime/active-skill.json`; falls back to the
+ * legacy `.peaks/.active-skill.json` for one minor release.
+ *
+ * Returns the parsed SkillPresence object, or null when neither
+ * file is present / valid. The legacy file is never written by
+ * current code — only the new path receives writes.
+ */
+function readSkillPresenceBackCompat(projectRootOverride) {
+    const presencePath = resolvePresencePath(projectRootOverride);
+    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
+    const pathToRead = existsSync(presencePath) ? presencePath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
+            return null;
+        }
+        return { presence: parsed, path: pathToRead };
+    }
+    catch {
+        return null;
+    }
+}
 function getCurrentSessionId(projectRootOverride) {
-    const sessionPath = resolve(resolveProjectRoot(projectRootOverride), SESSION_FILE);
-    if (!existsSync(sessionPath))
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const sessionPath = resolve(projectRoot, SESSION_FILE);
+    const legacyPath = resolve(projectRoot, SESSION_FILE_LEGACY);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` for one minor release.
+    const pathToRead = existsSync(sessionPath) ? sessionPath : legacyPath;
+    if (!existsSync(pathToRead))
         return null;
     try {
-        const data = JSON.parse(readFileSync(sessionPath, 'utf8'));
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
         return typeof data.sessionId === 'string' && data.sessionId.length > 0
             ? data.sessionId
             : null;
@@ -80,7 +120,7 @@ function getBoundOuterSessionId(projectRootOverride) {
 }
 /**
  * Snapshot of the previous peaks session's outer session id, read
- * straight off `.peaks/.active-skill.json` *before* we overwrite it.
+ * straight off the active-skill marker *before* we overwrite it.
  * Used to detect "the LLM just opened a fresh outer session" — if
  * the previously-recorded outer session id differs from the one we
  * are about to stamp, the user probably closed the previous outer
@@ -93,27 +133,24 @@ function getBoundOuterSessionId(projectRootOverride) {
  * (most common when the swap is a no-op reconnect) or to roll a
  * fresh session (when the new outer session is genuinely a new
  * task).
+ *
+ * Reads from `.peaks/_runtime/active-skill.json` first; falls back to
+ * the legacy `.peaks/.active-skill.json` for one minor release.
  */
 function getPreviousOuterSessionId(projectRootOverride) {
-    const presencePath = resolvePresencePath(projectRootOverride);
-    if (!existsSync(presencePath))
-        return undefined;
-    try {
-        const raw = readFileSync(presencePath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed.outerSessionId === 'string' && parsed.outerSessionId.length > 0) {
-            return parsed.outerSessionId;
-        }
-        // Legacy field name. Honour it on the read side so v1.2.x
-        // presence files do not show as a false mismatch.
-        if (typeof parsed.claudeSessionId === 'string' && parsed.claudeSessionId.length > 0) {
-            return parsed.claudeSessionId;
-        }
+    const result = readSkillPresenceBackCompat(projectRootOverride);
+    if (result === null)
         return undefined;
+    const parsed = result.presence;
+    if (typeof parsed.outerSessionId === 'string' && parsed.outerSessionId.length > 0) {
+        return parsed.outerSessionId;
     }
-    catch {
-        return undefined;
+    // Legacy field name. Honour it on the read side so v1.2.x
+    // presence files do not show as a false mismatch.
+    if (typeof parsed.claudeSessionId === 'string' && parsed.claudeSessionId.length > 0) {
+        return parsed.claudeSessionId;
     }
+    return undefined;
 }
 export function exportSkillPresence(projectRootOverride) {
     return resolvePresencePath(projectRootOverride);
@@ -184,65 +221,62 @@ export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     return presence;
 }
 export function getSkillPresence(projectRootOverride) {
-    const presencePath = resolvePresencePath(projectRootOverride);
-    if (!existsSync(presencePath)) {
+    const result = readSkillPresenceBackCompat(projectRootOverride);
+    if (result === null)
         return null;
-    }
-    try {
-        const raw = readFileSync(presencePath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
-            return null;
-        }
-        if (typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0) {
-            const currentSessionId = getCurrentSessionId(projectRootOverride);
-            if (currentSessionId && parsed.sessionId !== currentSessionId) {
+    const { presence, path: presencePath } = result;
+    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
+        const currentSessionId = getCurrentSessionId(projectRootOverride);
+        if (currentSessionId && presence.sessionId !== currentSessionId) {
+            try {
                 unlinkSync(presencePath);
-                return null;
             }
+            catch {
+                // best effort
+            }
+            return null;
         }
-        return parsed;
-    }
-    catch {
-        return null;
     }
+    return presence;
 }
 export function touchSkillHeartbeat(projectRootOverride) {
-    const presencePath = resolvePresencePath(projectRootOverride);
-    if (!existsSync(presencePath)) {
+    const result = readSkillPresenceBackCompat(projectRootOverride);
+    if (result === null)
         return null;
-    }
-    try {
-        const raw = readFileSync(presencePath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
-            return null;
-        }
-        if (typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0) {
-            const currentSessionId = getCurrentSessionId(projectRootOverride);
-            if (currentSessionId && parsed.sessionId !== currentSessionId) {
+    const { presence, path: presencePath } = result;
+    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
+        const currentSessionId = getCurrentSessionId(projectRootOverride);
+        if (currentSessionId && presence.sessionId !== currentSessionId) {
+            try {
                 unlinkSync(presencePath);
-                return null;
             }
+            catch {
+                // best effort
+            }
+            return null;
         }
-        parsed.lastHeartbeat = new Date().toISOString();
-        writeFileSync(presencePath, JSON.stringify(parsed, null, 2), 'utf8');
-        return parsed;
-    }
-    catch {
-        return null;
     }
+    presence.lastHeartbeat = new Date().toISOString();
+    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    return presence;
 }
 export function clearSkillPresence(projectRootOverride) {
+    // Clear both the new canonical path and the legacy path, so a stale
+    // presence marker from a prior CLI version cannot resurrect after
+    // a fresh `clear`.
     const presencePath = resolvePresencePath(projectRootOverride);
-    if (!existsSync(presencePath)) {
-        return false;
-    }
-    try {
-        unlinkSync(presencePath);
-        return true;
-    }
-    catch {
-        return false;
+    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
+    let cleared = false;
+    for (const p of [presencePath, legacyPath]) {
+        if (!existsSync(p))
+            continue;
+        try {
+            unlinkSync(p);
+            cleared = true;
+        }
+        catch {
+            // best effort
+        }
     }
+    return cleared;
 }

package/dist/src/services/skills/skill-runbook-service.js

@@ -1,3 +1,4 @@
+import { dirname, join } from 'node:path';
 import { readText } from '../../shared/fs.js';
 import { loadSkillRegistry } from './skill-registry.js';
 const DESTRUCTIVE_APPLY_PATTERNS = [
@@ -5,7 +6,8 @@ const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+extract[^\n]*--apply/,
     /peaks\s+artifacts\s+sync[^\n]*--apply/,
     /peaks\s+openspec\s+archive[^\n]*--apply/,
-    /peaks\s+standards\s+(?:init|update)[^\n]*--apply/
+    /peaks\s+standards\s+(?:init|update)[^\n]*--apply/,
+    /peaks\s+workspace\s+reconcile[^\n]*--apply/
 ];
 const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
 const PEAKS_COMMAND_LINE_PATTERN = /^\s*peaks\s+\w/;
@@ -13,6 +15,38 @@ function extractRunbookSection(body) {
     const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
     return match === null ? null : match[1];
 }
+/**
+ * Load the runbook section, falling back to `references/runbook.md` if the
+ * SKILL.md only has a pointer section. This supports skills (notably
+ * `peaks-solo`) that extracted their 150-line bash runbook to a sibling
+ * reference to keep SKILL.md under the 800-line cap. The CLI
+ * `peaks skill runbook` command uses the same fallback so a human
+ * reviewer sees the full runbook regardless of where it lives.
+ *
+ * Strategy: prefer the LONGER of the two sections. A short pointer section
+ * in SKILL.md (~ 1-2 lines) is treated as a "this runbook is in the
+ * reference" marker; a long inline section (>= the reference length) is
+ * treated as the canonical runbook. This avoids the false positive where
+ * the pointer section's regex match returns a non-null but content-poor
+ * string.
+ */
+async function loadRunbookSection(skillPath, body) {
+    const inline = extractRunbookSection(body);
+    const refPath = join(dirname(skillPath), 'references', 'runbook.md');
+    let refSection = null;
+    try {
+        const refBody = await readText(refPath);
+        refSection = extractRunbookSection(refBody);
+    }
+    catch {
+        // reference file does not exist or is not readable
+    }
+    if (inline === null)
+        return refSection;
+    if (refSection === null)
+        return inline;
+    return inline.length >= refSection.length ? inline : refSection;
+}
 function findDestructiveApplyLines(section) {
     const lines = section.split(/\r?\n/);
     return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
@@ -30,7 +64,7 @@ export async function inspectSkillRunbook(name, baseDir) {
         throw new Error(`Skill "${name}" not found under skills directory`);
     }
     const body = await readText(skill.skillPath);
-    const section = extractRunbookSection(body);
+    const section = await loadRunbookSection(skill.skillPath, body);
     if (section === null) {
         return {
             name: skill.name,

package/dist/src/services/skills/skill-statusline-service.js

@@ -6,16 +6,19 @@ import { findProjectRoot } from '../config/config-safety.js';
  *
  * Claude Code invokes the configured statusLine command on every turn and pipes
  * a JSON session payload on stdin. This renderer reads the durable presence file
- * (.peaks/.active-skill.json) and prints a single line that Claude Code paints at
- * the bottom of the terminal. Because it is rendered by the harness — not emitted
- * as LLM tokens — the signal cannot be forgotten by the model, cannot be confused
- * with normal output, and survives context compaction.
+ * (`.peaks/_runtime/active-skill.json`, with a one-minor-release back-compat
+ * fallback to `.peaks/.active-skill.json`) and prints a single line that
+ * Claude Code paints at the bottom of the terminal. Because it is rendered
+ * by the harness — not emitted as LLM tokens — the signal cannot be forgotten
+ * by the model, cannot be confused with normal output, and survives context
+ * compaction.
  *
  * This module is intentionally READ-ONLY. Unlike getSkillPresence in
  * skill-presence-service.ts, it never deletes or rewrites the presence file:
  * the statusLine runs on every turn and must have zero side effects.
  */
-const PRESENCE_FILE = '.peaks/.active-skill.json';
+const PRESENCE_FILE = '.peaks/_runtime/active-skill.json';
+const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
 const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 function resolveCwdFromStdin(stdin) {
     const fromWorkspace = stdin?.workspace?.current_dir ?? stdin?.workspace?.project_dir;
@@ -48,11 +51,14 @@ export function parseStatusLineStdin(raw) {
  */
 function readPresenceReadOnly(projectRoot) {
     const presencePath = resolve(projectRoot, PRESENCE_FILE);
-    if (!existsSync(presencePath)) {
+    // Back-compat: prefer the new canonical path; fall back to the legacy
+    // `.peaks/.active-skill.json` for one minor release.
+    const pathToRead = existsSync(presencePath) ? presencePath : resolve(projectRoot, PRESENCE_FILE_LEGACY);
+    if (!existsSync(pathToRead)) {
         return { presence: null, invalid: false };
     }
     try {
-        const parsed = JSON.parse(readFileSync(presencePath, 'utf8'));
+        const parsed = JSON.parse(readFileSync(pathToRead, 'utf8'));
         if (!parsed || typeof parsed !== 'object') {
             return { presence: null, invalid: true };
         }

package/dist/src/services/workflow/autonomous-resume-writer.js

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { buildArtifactRelativePath, validateChangeIdOrThrow } from '../../shared/change-id.js';
+import { buildArtifactRelativePathInRoot, validateChangeIdOrThrow } from '../../shared/change-id.js';
 import { pathExists } from '../../shared/fs.js';
 function defaultClock() {
     return new Date().toISOString();
@@ -109,27 +109,27 @@ Next actions:
 function buildFiles(changeId, goal, createdAt, artifactWorkspacePath) {
     return [
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'prd', 'autonomous-goal-package.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'prd', 'autonomous-goal-package.json')),
             content: renderGoalPackage(changeId, goal)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'autonomous-rd-plan.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'autonomous-rd-plan.json')),
             content: renderRdPlan(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'checkpoints', 'checkpoint-1.json')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'checkpoints', 'checkpoint-1.json')),
             content: renderCheckpoint(changeId, createdAt)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'evidence', 'unit-tests.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'evidence', 'unit-tests.md')),
             content: renderUnitTestsEvidence(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'evidence', 'validation-report.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'evidence', 'validation-report.md')),
             content: renderValidationReport(changeId)
         },
         {
-            path: join(artifactWorkspacePath, buildArtifactRelativePath(changeId, 'rd', 'swarm', 'resume-instructions.md')),
+            path: join(artifactWorkspacePath, buildArtifactRelativePathInRoot(artifactWorkspacePath, changeId, 'rd', 'swarm', 'resume-instructions.md')),
             content: renderResumeInstructions(changeId)
         }
     ];

package/dist/src/services/workspace/reconcile-service.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Reconcile service for `.peaks/2026-MM-DD-session-<6hex>/` directories.
+ *
+ * Reconcile scans the project root's `.peaks/` directory, identifies a
+ * canonical session via a 4-tier heuristic, re-points
+ * `.peaks/_runtime/session.json` (the canonical new home of the
+ * binding; legacy `.peaks/.session.json` is read-only back-compat),
+ * and (optionally, with apply === true) deletes empty / abandoned
+ * session dirs older than olderThanMs.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the top-level orchestrator
+ * also runs `migrateOldRuntimeState` at the start so pre-migration
+ * trees have their `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * / `.peaks/sop-state/` files moved into `.peaks/_runtime/`.
+ *
+ * Pure hand-rolled; uses only node:fs, node:path, and the existing
+ * session-manager helper for writing the binding. No new dependencies.
+ */
+import type { ReconcileOptions, ReconcileResult, SessionEntry } from './reconcile-types.js';
+/**
+ * Walk the project root's `.peaks/` directory and return an entry per
+ * session dir matching the standard naming pattern, sorted by name
+ * ascending (the most recent is last by sort order, since the date
+ * prefix dominates the lexicographic order).
+ *
+ * Each entry's `lastActivity` is the mtime of the inner `session.json`
+ * file, or null if that file is missing. `artifactCount` is the count
+ * of files under the dir excluding `session.json` itself.
+ */
+export declare function discoverSessions(projectRoot: string): SessionEntry[];
+/**
+ * 4-tier canonical selection. Tiers evaluated in order; first one that
+ * yields a session id wins.
+ *
+ *   1. active-skill sessionId, if it matches a real entry
+ *   2. entry with the most recent `session.json` mtime
+ *   3. entry with the most recent mtime of any file inside it
+ *   4. entry whose dir name sorts last lexicographically
+ */
+export declare function pickCanonicalSession(entries: SessionEntry[], activeSkillSessionId: string | null): {
+    sessionId: string;
+    source: ReconcileResult['canonicalSource'];
+} | null;
+/**
+ * Write `.peaks/.session.json` to bind the project to `canonicalSessionId`.
+ * Preserves the projectRoot. The previous binding is returned so the CLI
+ * can surface the re-point delta.
+ */
+export declare function repointSessionJson(projectRoot: string, canonicalSessionId: string, repointedFrom: string | null): {
+    repointedFrom: string | null;
+    repointedTo: string;
+};
+/**
+ * Identify deletion candidates. A session is a candidate when:
+ *   - the resolved `lastActivity` is older than `ageThresholdMs`, AND
+ *   - the dir is "empty or auto-only" (artifactCount === 0, OR the
+ *     only file is `session.json` which is auto-generated).
+ *
+ * If `lastActivity` is null (no `session.json` inside), the session's
+ * own dir mtime is used as a fallback so empty dirs without inner
+ * metadata are still fair-game.
+ */
+export declare function findDeletionCandidates(entries: SessionEntry[], ageThresholdMs: number): SessionEntry[];
+/**
+ * Apply or report deletion of the given candidates. When `apply` is
+ * false, just return `wouldDelete` and do not touch disk. When `apply`
+ * is true, actually `rm -rf` each dir and accumulate any per-dir
+ * errors in the result.
+ */
+export declare function applyDeletions(candidates: SessionEntry[], apply: boolean): {
+    deleted: string[];
+    wouldDelete: string[];
+    errors: Array<{
+        sessionId: string;
+        message: string;
+    }>;
+};
+/**
+ * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
+ *
+ * Move the legacy runtime files at:
+ *   - `.peaks/.session.json`
+ *   - `.peaks/.active-skill.json`
+ *   - `.peaks/sop-state/`
+ * into their new canonical home at:
+ *   - `.peaks/_runtime/session.json`
+ *   - `.peaks/_runtime/active-skill.json`
+ *   - `.peaks/_runtime/sop-state/`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new
+ *     layout produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` (atomic on POSIX, best-effort
+ *     on Windows) and falls back to `copyFileSync` + `unlinkSync` if
+ *     rename throws (e.g. cross-device move on Windows). Errors are
+ *     collected per file and returned in the `errors` array so the
+ *     reconcile envelope can surface them without blocking the rest of
+ *     the migration.
+ *   - Creates `.peaks/_runtime/` on demand if any of the old paths
+ *     are present.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the
+ *   *old* relative paths (e.g. `.peaks/.session.json`) that were
+ *   successfully moved, in move order. `errors` lists per-file
+ *   failures with the old path and a human-readable message.
+ */
+export declare function migrateOldRuntimeState(projectRoot: string): {
+    migratedFiles: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/**
+ * Top-level orchestrator. Wires migration (added in slice
+ * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,
+ * deletion-candidate selection, and deletion into a single result.
+ */
+export declare function reconcileWorkspace(options: ReconcileOptions): ReconcileResult;