peaks-cli 1.2.9 → 1.3.1

package/dist/src/services/artifacts/request-artifact-service.js

@@ -4,6 +4,7 @@ import { dirname, join } from 'node:path';
 import { isDirectory, listDirectories } from '../../shared/fs.js';
 import { checkPrerequisites, DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES } from './artifact-prerequisites.js';
 import { ensureSession } from '../session/session-manager.js';
+import { getCurrentChangeId, getChangeArtifactRoot } from '../../shared/change-id.js';
 import { getNextNumber, buildNumberedFilename } from '../../shared/incrementing-number.js';
 import { lintRequestArtifact } from './artifact-lint-service.js';
 import { checkTypeSanity } from '../scan/type-sanity-service.js';
@@ -21,10 +22,11 @@ function dateSlugFromIso(iso) {
 function defaultSessionId(iso) {
     return `${dateSlugFromIso(iso)}-session`;
 }
-function renderPrdTemplate(requestId, sessionId, timestamp, requestType) {
+function renderPrdTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# PRD Request ${requestId}
 
 - session: ${sessionId}
+- change-id: ${changeId}
 - type: ${requestType}
 - source: <ticket, message URL, or "verbal" with a short sanitized quote>
 - raw input (sanitized): <one-paragraph restatement of what the user actually asked for>
@@ -57,9 +59,9 @@ function renderPrdTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-rd: .peaks/${sessionId}/rd/requests/${requestId}.md
-- to peaks-qa: .peaks/${sessionId}/qa/requests/${requestId}.md
-- to peaks-ui: .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- to peaks-rd: .peaks/${changeId}/rd/requests/${requestId}.md
+- to peaks-qa: .peaks/${changeId}/qa/requests/${requestId}.md
+- to peaks-ui: .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 
 ## Status
 
@@ -68,11 +70,12 @@ function renderPrdTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderUiTemplate(requestId, sessionId, timestamp, requestType) {
+function renderUiTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# UI Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
 - type: ${requestType}
 - scope: full new surface | iteration on existing surface | regression fix | visual refresh
 - design direction: editorial | bento | Swiss | luxury | retro-futurist | glass | product-system | other-explicit-name
@@ -108,8 +111,8 @@ function renderUiTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-rd: .peaks/${sessionId}/rd/requests/${requestId}.md
-- to peaks-qa: .peaks/${sessionId}/qa/requests/${requestId}.md
+- to peaks-rd: .peaks/${changeId}/rd/requests/${requestId}.md
+- to peaks-qa: .peaks/${changeId}/qa/requests/${requestId}.md
 
 ## Status
 
@@ -118,12 +121,13 @@ function renderUiTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderRdTemplate(requestId, sessionId, timestamp, requestType) {
+function renderRdTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# RD Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
-- linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
+- linked-ui:  .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 - type: ${requestType}
 
 ## Red-line scope
@@ -165,8 +169,8 @@ function renderRdTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-qa: .peaks/${sessionId}/qa/requests/${requestId}.md
-- to peaks-sc: .peaks/${sessionId}/sc/commit-boundaries/${requestId}.md
+- to peaks-qa: .peaks/${changeId}/qa/requests/${requestId}.md
+- to peaks-sc: .peaks/${changeId}/sc/commit-boundaries/${requestId}.md
 
 ## Status
 
@@ -175,13 +179,14 @@ function renderRdTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderQaTemplate(requestId, sessionId, timestamp, requestType) {
+function renderQaTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# QA Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
-- linked-rd:  .peaks/${sessionId}/rd/requests/${requestId}.md
-- linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
+- linked-rd:  .peaks/${changeId}/rd/requests/${requestId}.md
+- linked-ui:  .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 - type: ${requestType}
 
 ## Red-line boundary check
@@ -230,14 +235,15 @@ function renderQaTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderScTemplate(requestId, sessionId, timestamp, requestType) {
+function renderScTemplate(requestId, changeId, sessionId, timestamp, requestType) {
     return `# SC Request ${requestId}
 
 - session: ${sessionId}
-- linked-prd: .peaks/${sessionId}/prd/requests/${requestId}.md
-- linked-rd:  .peaks/${sessionId}/rd/requests/${requestId}.md
-- linked-qa:  .peaks/${sessionId}/qa/requests/${requestId}.md
-- linked-ui:  .peaks/${sessionId}/ui/requests/${requestId}.md  (when UI involved)
+- change-id: ${changeId}
+- linked-prd: .peaks/${changeId}/prd/requests/${requestId}.md
+- linked-rd:  .peaks/${changeId}/rd/requests/${requestId}.md
+- linked-qa:  .peaks/${changeId}/qa/requests/${requestId}.md
+- linked-ui:  .peaks/${changeId}/ui/requests/${requestId}.md  (when UI involved)
 - type: ${requestType}
 
 ## Change impact
@@ -262,7 +268,7 @@ function renderScTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Sync / authorization
 
-- artifact workspace path: .peaks/${sessionId}/
+- artifact workspace path: .peaks/${changeId}/
 - memory sync authorized: yes | no
 - artifact sync authorized: yes | no
 - rationale if not authorized: keep local
@@ -273,7 +279,7 @@ function renderScTemplate(requestId, sessionId, timestamp, requestType) {
 
 ## Handoff
 
-- to peaks-txt: .peaks/${sessionId}/txt/skill-usage-lessons.md (when reusable lesson exists)
+- to peaks-txt: .peaks/${changeId}/txt/skill-usage-lessons.md (when reusable lesson exists)
 
 ## Status
 
@@ -282,18 +288,18 @@ function renderScTemplate(requestId, sessionId, timestamp, requestType) {
 - state: draft
 `;
 }
-function renderTemplate(role, requestId, sessionId, timestamp, requestType) {
+function renderTemplate(role, requestId, changeId, sessionId, timestamp, requestType) {
     switch (role) {
         case 'prd':
-            return renderPrdTemplate(requestId, sessionId, timestamp, requestType);
+            return renderPrdTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'ui':
-            return renderUiTemplate(requestId, sessionId, timestamp, requestType);
+            return renderUiTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'rd':
-            return renderRdTemplate(requestId, sessionId, timestamp, requestType);
+            return renderRdTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'qa':
-            return renderQaTemplate(requestId, sessionId, timestamp, requestType);
+            return renderQaTemplate(requestId, changeId, sessionId, timestamp, requestType);
         case 'sc':
-            return renderScTemplate(requestId, sessionId, timestamp, requestType);
+            return renderScTemplate(requestId, changeId, sessionId, timestamp, requestType);
     }
 }
 export async function createRequestArtifact(options) {
@@ -306,10 +312,26 @@ export async function createRequestArtifact(options) {
     const requestType = options.requestType ?? DEFAULT_REQUEST_TYPE;
     const clock = options.clock ?? defaultClock;
     const timestamp = clock();
-    // Use provided session ID or get/create current session
+    // Use provided session ID or get/create current session. The session
+    // id is kept as the in-memory binding (so the artifact body can record
+    // which session wrote it), but the artifact file is now written
+    // under the change-id dir, NOT the session dir.
+    //
+    // The change-id is the file's durable scope. As of slice
+    // 2026-06-05-change-id-as-unit-of-work, the requestId IS the
+    // change-id (per the legacy `001-<change-id>.md` filename convention);
+    // a request that lives in a session dir under a different change-id
+    // is no longer the model. We honor a `current-change` binding if
+    // one is set, and otherwise fall back to the requestId itself.
     const sessionId = options.sessionId ?? await ensureSession(options.projectRoot);
-    // Build numbered path in session directory
-    const requestsDir = join(options.projectRoot, '.peaks', sessionId, options.role, 'requests');
+    const boundChangeId = getCurrentChangeId(options.projectRoot);
+    // Resolution order for the change-id (file path key):
+    //   1. Explicit `options.changeId` (CLI `--session-id` pre-1.3.0 set this).
+    //   2. `current-change` binding (live developer working context).
+    //   3. The requestId itself (every request is its own scope by default).
+    const changeId = options.changeId ?? boundChangeId ?? options.requestId;
+    // Build numbered path under the change-id dir
+    const requestsDir = getChangeArtifactRoot(options.projectRoot, changeId) + '/' + options.role + '/requests';
     // Check if a file with this requestId already exists (regardless of number prefix)
     if (await isDirectory(requestsDir)) {
         const existingFiles = await listMarkdownFiles(requestsDir);
@@ -327,15 +349,18 @@ export async function createRequestArtifact(options) {
     const number = getNextNumber(requestsDir);
     const filename = buildNumberedFilename(number, options.requestId);
     const path = join(requestsDir, filename);
-    const content = renderTemplate(options.role, options.requestId, sessionId, timestamp, requestType);
+    const content = renderTemplate(options.role, options.requestId, changeId, sessionId, timestamp, requestType);
     if (options.apply !== true) {
         return { role: options.role, requestId: options.requestId, sessionId, path, content, applied: false };
     }
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, content, 'utf8');
-    // Create QA initiated marker so rd:qa-handoff gate can verify QA was invoked
+    // Create QA initiated marker so rd:qa-handoff gate can verify QA was invoked.
+    // As of slice 2026-06-05-change-id-as-unit-of-work, the marker lives under
+    // the change-id dir (not the session dir), so the gate's prereq scan
+    // (which reads from `.peaks/<change-id>/<role>/...`) finds it.
     if (options.role === 'qa') {
-        const qaDir = join(options.projectRoot, '.peaks', sessionId, 'qa');
+        const qaDir = getChangeArtifactRoot(options.projectRoot, changeId) + '/qa';
         const initiatedPath = join(qaDir, '.initiated');
         if (!existsSync(initiatedPath)) {
             await mkdir(qaDir, { recursive: true });
@@ -348,6 +373,7 @@ function extractMetadata(markdown) {
     let state = 'unknown';
     let createdAt;
     let requestType = DEFAULT_REQUEST_TYPE;
+    let sessionId;
     for (const rawLine of markdown.split(/\r?\n/)) {
         const line = rawLine.trim();
         const stateMatch = /^-\s*state:\s*(.+?)\s*$/.exec(line);
@@ -367,21 +393,41 @@ function extractMetadata(markdown) {
                 requestType = candidate;
             }
             // Placeholder values (e.g. "feature | bug | refactor | clarification") fall back to default.
+            continue;
+        }
+        const sessionMatch = /^-\s*session:\s*(.+?)\s*$/.exec(line);
+        if (sessionMatch !== null && sessionMatch[1] !== undefined) {
+            sessionId = sessionMatch[1];
+            continue;
         }
     }
     const base = { state, requestType };
     if (createdAt !== undefined)
         base.createdAt = createdAt;
+    if (sessionId !== undefined)
+        base.sessionId = sessionId;
     return base;
 }
-async function readSummary(projectRoot, sessionId, role, fileName) {
-    const path = join(projectRoot, '.peaks', sessionId, role, 'requests', fileName);
+async function readSummary(projectRoot, changeId, role, fileName) {
+    const path = join(projectRoot, '.peaks', changeId, role, 'requests', fileName);
     const body = await readFile(path, 'utf8');
-    const { state, createdAt, requestType } = extractMetadata(body);
+    const { state, createdAt, requestType, sessionId: bodySessionId } = extractMetadata(body);
     // Strip numbered prefix (e.g., "001-requestId.md" -> "requestId")
     // Only strip 3-digit zero-padded prefixes (our incrementing number format)
     const requestId = fileName.replace(/^0\d{2}-/, '').replace(/\.md$/, '');
-    const summary = { role, sessionId, requestId, path, state, requestType };
+    // `changeId` is the durable scope (the directory the file lives in).
+    // `sessionId` is metadata (the session that wrote the file, parsed from
+    // the `- session:` body line). They may differ when a request is read
+    // across sessions (back-compat) or after a session re-bind.
+    const summary = {
+        role,
+        changeId,
+        sessionId: bodySessionId ?? changeId,
+        requestId,
+        path,
+        state,
+        requestType
+    };
     if (createdAt !== undefined) {
         summary.createdAt = createdAt;
     }
@@ -402,15 +448,53 @@ export async function listRequestArtifacts(options) {
     if (!(await isDirectory(peaksRoot))) {
         return [];
     }
-    const sessions = options.sessionId !== undefined ? [options.sessionId] : await listDirectories(peaksRoot);
+    // As of slice 2026-06-05-change-id-as-unit-of-work, artifact files live
+    // in `.peaks/<change-id>/<role>/requests/`. The top-level `.peaks/<dir>/`
+    // entries we scan here are change-id dirs (new layout) AND legacy
+    // session-id dirs (pre-1.3.0 layout). Both have the same
+    // `<role>/requests/<file>.md` shape, so we read them uniformly.
+    //
+    // Additionally, shipped slices are archived under
+    // `.peaks/retrospective/<change-id>/<role>/requests/` and dogfood
+    // evidence lives under `.peaks/_dogfood/<change-id>/<role>/requests/`.
+    // When `sessionId` is NOT pinned, we scan ALL three umbrella dirs
+    // (`<top>`, `retrospective/`, `_dogfood/`) so a `peaks request show
+    // <rid>` resolves shipped slices too — which is what the slice check's
+    // gate-verify-pipeline stage needs to find evidence for the retrospective
+    // slice being verified.
+    //
+    // Skip well-known non-artifact dirs: `_runtime/` holds ephemeral state
+    // (no `requests/` subdirs anyway, but skip explicitly to avoid noise).
+    const allDirs = await listDirectories(peaksRoot);
+    const candidateDirs = allDirs.filter((dir) => dir !== '_runtime');
+    // Expand scopes to include the nested umbrellas that host change-id dirs
+    // (retrospective/, _dogfood/). For each, list its sub-dirs and treat
+    // them as additional scopes. This makes the lookup span the entire
+    // .peaks tree.
+    const expandedScopes = [];
+    if (options.sessionId !== undefined) {
+        expandedScopes.push(options.sessionId);
+    }
+    else {
+        for (const dir of candidateDirs) {
+            expandedScopes.push(dir);
+            if (dir === 'retrospective' || dir === '_dogfood') {
+                const nested = await listDirectories(join(peaksRoot, dir));
+                for (const n of nested) {
+                    expandedScopes.push(join(dir, n));
+                }
+            }
+        }
+    }
+    const scopes = expandedScopes;
     const roles = options.role !== undefined ? [options.role] : Array.from(VALID_ROLES);
     const summaries = [];
-    for (const sessionId of sessions) {
+    for (const scope of scopes) {
         for (const role of roles) {
-            const dir = join(peaksRoot, sessionId, role, 'requests');
+            const dir = join(peaksRoot, scope, role, 'requests');
             const fileNames = await listMarkdownFiles(dir);
             for (const fileName of fileNames) {
-                summaries.push(await readSummary(options.projectRoot, sessionId, role, fileName));
+                summaries.push(await readSummary(options.projectRoot, scope, role, fileName));
             }
         }
     }
@@ -438,32 +522,65 @@ export async function showRequestArtifact(options) {
         }
         return null;
     };
+    // As of slice 2026-06-05-change-id-as-unit-of-work, the dir key is the
+    // change-id (not the session-id). When the caller pins `sessionId` we
+    // use it as the scope anyway (legacy callers, and tests that pass
+    // `STABLE_SESSION` as a stand-in). The directory layout is identical
+    // for both old session dirs and new change-id dirs, so a single
+    // read path works for both.
     if (options.sessionId !== undefined) {
         const dir = join(options.projectRoot, '.peaks', options.sessionId, options.role, 'requests');
         const found = await findFileInDir(dir);
         if (found === null) {
             return null;
         }
-        const summary = await readSummary(options.projectRoot, options.sessionId, options.role, found.fileName);
-        const content = await readFile(found.path, 'utf8');
-        return { ...summary, content };
+        return await readRequestArtifact(options.projectRoot, options.sessionId, options.role, found);
     }
     const peaksRoot = join(options.projectRoot, '.peaks');
     if (!(await isDirectory(peaksRoot))) {
         return null;
     }
-    const sessions = await listDirectories(peaksRoot);
-    for (const sessionId of sessions) {
-        const dir = join(peaksRoot, sessionId, options.role, 'requests');
+    // Scan all top-level dirs in `.peaks/` AND nested change-id dirs
+    // under `retrospective/` and `_dogfood/`. The expanded scope list
+    // lets us find request artifacts that live one or two levels deep
+    // (shipped slices, dogfood evidence). Without this expansion,
+    // verify-pipeline can't find the RD/QA request files for any
+    // retrospective slice.
+    const allDirs = await listDirectories(peaksRoot);
+    const scopes = [];
+    for (const dir of allDirs) {
+        if (dir === '_runtime')
+            continue;
+        scopes.push(dir);
+        if (dir === 'retrospective' || dir === '_dogfood') {
+            const nested = await listDirectories(join(peaksRoot, dir));
+            for (const n of nested) {
+                scopes.push(join(dir, n));
+            }
+        }
+    }
+    for (const scope of scopes) {
+        const dir = join(peaksRoot, scope, options.role, 'requests');
         const found = await findFileInDir(dir);
         if (found !== null) {
-            const summary = await readSummary(options.projectRoot, sessionId, options.role, found.fileName);
-            const content = await readFile(found.path, 'utf8');
-            return { ...summary, content };
+            return await readRequestArtifact(options.projectRoot, scope, options.role, found);
         }
     }
     return null;
 }
+/** Read the summary + content for a found request file; treat a read
+ * error on the content as "not found" so the caller can fall through
+ * to the next candidate (the on-disk file may be partially written). */
+async function readRequestArtifact(projectRoot, scope, role, found) {
+    const summary = await readSummary(projectRoot, scope, role, found.fileName);
+    try {
+        const content = await readFile(found.path, 'utf8');
+        return { ...summary, content };
+    }
+    catch {
+        return null;
+    }
+}
 const ALLOWED_STATES_PER_ROLE = {
     prd: ['draft', 'confirmed-by-user', 'handed-off', 'blocked'],
     ui: ['draft', 'direction-locked', 'handed-off', 'blocked'],
@@ -601,7 +718,7 @@ export async function transitionRequestArtifact(options) {
     });
     const prerequisiteResult = await checkPrerequisites({
         projectRoot: options.projectRoot,
-        sessionId: existing.sessionId,
+        changeId: existing.changeId,
         role: options.role,
         newState: options.newState,
         requestId: options.requestId,
@@ -653,6 +770,7 @@ export async function transitionRequestArtifact(options) {
     await writeFile(existing.path, updated, 'utf8');
     const result = {
         role: options.role,
+        changeId: existing.changeId,
         sessionId: existing.sessionId,
         requestId: options.requestId,
         path: existing.path,

package/dist/src/services/doctor/doctor-service.d.ts

@@ -30,4 +30,11 @@ export type DoctorOptions = {
     /** Platform string (defaults to process.platform); injectable for tests. */
     platform?: NodeJS.Platform;
 };
+/**
+ * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
+ * drive the filesystem check without monkey-patching `process.cwd()` or
+ * `findProjectRoot`. Returns `true` when EITHER the canonical
+ * `.peaks/_runtime/session.json` OR the legacy `.peaks/.session.json` exists.
+ */
+export declare function isWorkspaceInitializedAt(projectRoot: string): boolean;
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

package/dist/src/services/doctor/doctor-service.js

@@ -48,7 +48,25 @@ function defaultWorkspaceInitializedProbe() {
     const projectRoot = findProjectRoot(process.cwd());
     if (projectRoot === null)
         return false;
-    return existsSync(join(projectRoot, '.peaks', '.session.json'));
+    // Workspace is "initialized" when EITHER the canonical runtime-layer session
+    // binding (`.peaks/_runtime/session.json`, the home since slice
+    // 2026-06-05-peaks-runtime-layer) OR the legacy top-level binding
+    // (`.peaks/.session.json`, kept as read-only back-compat for one minor
+    // release) is present. The legacy check is what catches projects that ran
+    // `peaks workspace init` before the runtime-layer migration and have not yet
+    // been reconciled; both paths must continue to satisfy the doctor until the
+    // legacy location is removed.
+    return isWorkspaceInitializedAt(projectRoot);
+}
+/**
+ * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
+ * drive the filesystem check without monkey-patching `process.cwd()` or
+ * `findProjectRoot`. Returns `true` when EITHER the canonical
+ * `.peaks/_runtime/session.json` OR the legacy `.peaks/.session.json` exists.
+ */
+export function isWorkspaceInitializedAt(projectRoot) {
+    return (existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json')) ||
+        existsSync(join(projectRoot, '.peaks', '.session.json')));
 }
 const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+sync[^\n]*--apply/,
@@ -234,7 +252,7 @@ export async function runDoctor(options = {}) {
         checks.push({
             id: 'skill-presence:workspace',
             ok: false,
-            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/.session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
+            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/_runtime/session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
         });
     }
     else {

package/dist/src/services/progress/progress-service.d.ts

@@ -164,6 +164,32 @@ export type ReadSpawnRecordResult = {
     reason: 'no-binding' | 'no-spawn-record' | 'invalid-json';
 };
 export declare function readSpawnRecord(projectRoot: string): ReadSpawnRecordResult;
+/**
+ * Idempotency check for the `peaks progress start` CLI (and the Task-tool
+ * PreToolUse hook that fires it on every Task call). Returns `true` when a
+ * recent spawn record exists for this project's session, meaning a watch
+ * window was opened within the last `ttlMs` milliseconds. The LLM-side
+ * caller treats `true` as "no-op — a watch is already running somewhere".
+ *
+ * Why TTL instead of pid liveness: the spawned terminal's pid is the
+ * osascript/gnome-terminal process, which exits as soon as it spawns the
+ * nested shell. Checking pid liveness gives false negatives (the process
+ * is gone by design). The spawn record is the canonical "watch was opened
+ * for this session" marker. After `ttlMs` the record is treated as stale
+ * (e.g. the user closed the window long ago) and a fresh start proceeds.
+ *
+ * `ttlMs` defaults to 5 minutes — long enough to cover a typical sub-agent
+ * slice (RD parallel fan-out + QA verdict), short enough that a user who
+ * closed the window gets a fresh one on the next Task call.
+ */
+export type RecentSpawnCheck = {
+    recent: boolean;
+    reason: 'recent-spawn' | 'no-spawn-record' | 'no-binding' | 'invalid-json' | 'stale-spawn' | 'process-dead';
+    /** When reason is 'recent-spawn' or 'stale-spawn', the spawn record. */
+    record?: ProgressSpawnRecord;
+    ageMs?: number;
+};
+export declare function isRecentSpawn(projectRoot: string, now?: () => number, ttlMs?: number): RecentSpawnCheck;
 export declare function clearSpawnRecord(projectRoot: string): boolean;
 export type PhaseClosingTrigger = 'finished' | 'failed';
 /**

package/dist/src/services/progress/progress-service.js

@@ -245,6 +245,31 @@ export function readSpawnRecord(projectRoot) {
         return { ok: false, reason: 'invalid-json' };
     }
 }
+export function isRecentSpawn(projectRoot, now = Date.now, ttlMs = 5 * 60 * 1000) {
+    const result = readSpawnRecord(projectRoot);
+    if (!result.ok) {
+        return { recent: false, reason: result.reason };
+    }
+    const record = result.data;
+    const spawnedMs = Date.parse(record.spawnedAt);
+    if (Number.isNaN(spawnedMs)) {
+        // Treat unparseable timestamps as a stale record so the next start
+        // proceeds normally. This is the conservative choice — the alternative
+        // (treating unparseable as "always recent") would block legitimate
+        // re-spawns forever.
+        return { recent: false, reason: 'stale-spawn', record };
+    }
+    const ageMs = now() - spawnedMs;
+    if (ageMs < 0) {
+        // Clock skew or future-dated record: trust the record as "recent" so
+        // we do not double-spawn. Same conservative default as a 0-age record.
+        return { recent: true, reason: 'recent-spawn', record, ageMs: 0 };
+    }
+    if (ageMs >= ttlMs) {
+        return { recent: false, reason: 'stale-spawn', record, ageMs };
+    }
+    return { recent: true, reason: 'recent-spawn', record, ageMs };
+}
 export function clearSpawnRecord(projectRoot) {
     const path = spawnRecordPath(projectRoot);
     if (!existsSync(path))

package/dist/src/services/sc/sc-service.d.ts

@@ -51,6 +51,52 @@ export type CommitBoundary = {
     syncState: 'synced' | 'pending' | 'failed';
     rollbackPoint: string | null;
 };
+/**
+ * Resolution sources for `resolveArtifactSession`, in priority order.
+ * - `active-skill`: the orchestrator's active-skill marker
+ *   (`.peaks/_runtime/active-skill.json`, with a one-minor-release
+ *   fallback to `.peaks/.active-skill.json`) `sessionId` points to a
+ *   session dir that owns the slice's marker artifact.
+ * - `session-json`: the workspace binding in
+ *   `.peaks/_runtime/session.json` (with back-compat fallback to
+ *   `.peaks/.session.json`) points to a session dir that owns the
+ *   slice's marker artifact (active-skill was checked but did not
+ *   own it; session-json is the next source).
+ * - `find-fallback`: neither binding owned the artifact, but a `find`
+ *   walk under `.peaks/` located a session dir that does own it.
+ */
+export type ArtifactSessionSource = 'active-skill' | 'session-json' | 'find-fallback';
+export type ResolvedArtifactSession = {
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
+};
+/**
+ * Resolve the session id that owns the slice's artifacts using a 3-tier
+ * precedence:
+ *
+ *   1. `.peaks/_runtime/active-skill.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.active-skill.json`) if it points to a real
+ *      session that owns the slice.
+ *   2. `.peaks/_runtime/session.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.session.json`) if it points to a real
+ *      session that owns the slice.
+ *   3. `find .peaks/ -name '<marker>'` — the first session dir under
+ *      `.peaks/` that owns the slice.
+ *   4. else `{ resolvedSessionId: null, candidateSources: [] }`.
+ *
+ * The back-compat fallbacks are tolerated for one minor release so
+ * users with pre-migration trees (or running an older CLI version)
+ * still get a clean resolution. After the migration (or after v1.3.0
+ * is installed and `peaks workspace reconcile` has been run), only
+ * the new paths exist and the fallbacks never fire.
+ *
+ * `candidateSources` reports which sources were checked before the
+ * resolver found (or did not find) a winner; the list is in the order
+ * the resolver consulted them. This makes the precedence observable in
+ * the JSON envelope so a human reviewer can see "active-skill was empty
+ * AND session-json was empty, so find-fallback won".
+ */
+export declare function resolveArtifactSession(projectRoot: string, sliceId: string): ResolvedArtifactSession;
 export declare function getChangeTraceabilityStatus(): ChangeTraceabilityStatus;
 export declare function createChangeImpact(options: {
     changeId: string;
@@ -71,10 +117,15 @@ export declare function recordCommitBoundary(options: {
     sliceId: string;
     artifacts?: string[];
     codeFiles?: string[];
-}): CommitBoundary;
+}): CommitBoundary & {
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
+};
 export declare function validateArtifactRetention(sliceId: string): {
     valid: boolean;
     missingArtifacts: string[];
     warnings: string[];
+    resolvedSessionId: string | null;
+    candidateSources: ArtifactSessionSource[];
 };
 export declare function getScHelpText(): string[];