peaks-cli 1.3.1 → 1.3.3

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

@@ -75,6 +75,39 @@ export declare function applyDeletions(candidates: SessionEntry[], apply: boolea
         message: string;
     }>;
 };
+/**
+ * Sync the single `change/<canonicalSessionId>/` live marker under
+ * `.peaks/_runtime/change/`. The marker is an EMPTY directory (no
+ * symlinks, no manifest, no content). Slice 006 collapses the F3
+ * per-change-id symlink layer to a single live marker so the
+ * `change/` layer is a single sentinel — easy for the LLM to
+ * navigate, easy for tests to assert on.
+ *
+ * Steps:
+ *   1. Ensure `.peaks/_runtime/change/` exists.
+ *   2. List its entries.
+ *   3. Remove every entry whose name is NOT `<canonicalSessionId>/`
+ *      (no-op for those whose name matches).
+ *   4. If `<canonicalSessionId>/` is missing, create it (empty).
+ *   5. Return the diff for telemetry.
+ *
+ * Path-traversal guards: the canonical session id is validated by
+ * the caller (`SESSION_ID_PATTERN` in the session-manager helper).
+ * The function only ever operates under the project-root-resolved
+ * `.peaks/_runtime/change/` dir, so the resolved paths cannot
+ * escape the project tree.
+ *
+ * @returns `{ removed, created, error }`:
+ *   - `removed`: list of entry names that were deleted (e.g. `['<oldSid>/']`).
+ *   - `created`: name of the new marker (e.g. `'<newSid>/'`) or null
+ *     when the canonical marker already existed (no-op).
+ *   - `error`: error message string or null.
+ */
+export declare function syncChangeMarker(projectRoot: string, canonicalSessionId: string): {
+    removed: string[];
+    created: string | null;
+    error: string | null;
+};
 /**
  * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
  *
@@ -111,6 +144,42 @@ export declare function migrateOldRuntimeState(projectRoot: string): {
         message: string;
     }>;
 };
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/<sid>/system/subagent-progress.json`
+ *   - `.peaks/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export declare function migrateSubAgentState(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,

package/dist/src/services/workspace/reconcile-service.js

@@ -16,11 +16,20 @@
  * Pure hand-rolled; uses only node:fs, node:path, and the existing
  * session-manager helper for writing the binding. No new dependencies.
  */
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { getSessionIdCanonical, setCurrentSessionBinding } from '../session/session-manager.js';
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
 const META_FILE = 'session.json';
+// Sub-agent state file basenames (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+// The legacy location was `.peaks/<sid>/system/<filename>`; the canonical new
+// location is `.peaks/_sub_agents/<sid>/<filename>`. `migrateSubAgentState`
+// moves the two files between these homes on every `reconcileWorkspace` run.
+const SUB_AGENT_MIGRATION_FILES = [
+    'subagent-progress.json',
+    'progress-spawn.json'
+];
+const SUB_AGENTS_DIR = '_sub_agents';
 // As of slice 2026-06-05-peaks-runtime-layer these old paths are the
 // back-compat read-only fallbacks; the canonical new home is
 // `.peaks/_runtime/`. `migrateOldRuntimeState` moves them to the new
@@ -55,59 +64,75 @@ function runtimeNewBasename(oldBasename) {
  * of files under the dir excluding `session.json` itself.
  */
 export function discoverSessions(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
     const peaksRoot = join(projectRoot, '.peaks');
-    if (!existsSync(peaksRoot))
-        return [];
-    let names;
-    try {
-        names = readdirSync(peaksRoot);
-    }
-    catch {
-        return [];
-    }
+    // As of slice 003, the canonical home for session dirs is
+    // `.peaks/_runtime/<sid>/`. The legacy top-level layout is
+    // read for back-compat (one minor release) so pre-migration
+    // trees keep working. Both are scanned; duplicates (same sid
+    // in both homes) are de-duplicated with the canonical home
+    // winning.
+    const seen = new Set();
     const entries = [];
-    for (const name of names) {
-        if (!SESSION_ID_PATTERN.test(name))
-            continue;
-        const dir = join(peaksRoot, name);
-        let stat;
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        let names;
         try {
-            // lstatSync: false for symlinks (prevents rm -rf from following a
-            // malicious symlink that points outside the project root).
-            stat = lstatSync(dir);
+            names = readdirSync(root);
         }
         catch {
-            continue;
+            return;
         }
-        if (!stat.isDirectory())
-            continue;
-        const metaPath = join(dir, META_FILE);
-        let lastActivity = null;
-        if (existsSync(metaPath)) {
-            try {
-                lastActivity = statSync(metaPath).mtimeMs;
-            }
-            catch {
-                lastActivity = null;
-            }
+        for (const name of names) {
+            if (!SESSION_ID_PATTERN.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            scanSessionDir(root, name, entries);
         }
-        let childNames;
+    };
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    entries.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+    return entries;
+}
+function scanSessionDir(peaksRoot, name, entries) {
+    const dir = join(peaksRoot, name);
+    let stat;
+    try {
+        stat = lstatSync(dir);
+    }
+    catch {
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    const metaPath = join(dir, META_FILE);
+    let lastActivity = null;
+    if (existsSync(metaPath)) {
         try {
-            childNames = readdirSync(dir);
+            lastActivity = statSync(metaPath).mtimeMs;
         }
         catch {
-            childNames = [];
+            lastActivity = null;
         }
-        let artifactCount = 0;
-        for (const child of childNames) {
-            if (child === META_FILE)
-                continue;
-            artifactCount += 1;
-        }
-        entries.push({ sessionId: name, path: dir, lastActivity, artifactCount });
     }
-    entries.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
-    return entries;
+    let childNames;
+    try {
+        childNames = readdirSync(dir);
+    }
+    catch {
+        childNames = [];
+    }
+    let artifactCount = 0;
+    for (const child of childNames) {
+        if (child === META_FILE)
+            continue;
+        artifactCount += 1;
+    }
+    entries.push({ sessionId: name, path: dir, lastActivity, artifactCount });
 }
 /**
  * 4-tier canonical selection. Tiers evaluated in order; first one that
@@ -299,6 +324,76 @@ function readActiveSkillSessionId(projectRoot) {
     }
     return null;
 }
+/**
+ * Sync the single `change/<canonicalSessionId>/` live marker under
+ * `.peaks/_runtime/change/`. The marker is an EMPTY directory (no
+ * symlinks, no manifest, no content). Slice 006 collapses the F3
+ * per-change-id symlink layer to a single live marker so the
+ * `change/` layer is a single sentinel — easy for the LLM to
+ * navigate, easy for tests to assert on.
+ *
+ * Steps:
+ *   1. Ensure `.peaks/_runtime/change/` exists.
+ *   2. List its entries.
+ *   3. Remove every entry whose name is NOT `<canonicalSessionId>/`
+ *      (no-op for those whose name matches).
+ *   4. If `<canonicalSessionId>/` is missing, create it (empty).
+ *   5. Return the diff for telemetry.
+ *
+ * Path-traversal guards: the canonical session id is validated by
+ * the caller (`SESSION_ID_PATTERN` in the session-manager helper).
+ * The function only ever operates under the project-root-resolved
+ * `.peaks/_runtime/change/` dir, so the resolved paths cannot
+ * escape the project tree.
+ *
+ * @returns `{ removed, created, error }`:
+ *   - `removed`: list of entry names that were deleted (e.g. `['<oldSid>/']`).
+ *   - `created`: name of the new marker (e.g. `'<newSid>/'`) or null
+ *     when the canonical marker already existed (no-op).
+ *   - `error`: error message string or null.
+ */
+export function syncChangeMarker(projectRoot, canonicalSessionId) {
+    const root = resolve(projectRoot);
+    const changeDir = join(root, '.peaks', '_runtime', 'change');
+    const removed = [];
+    let created = null;
+    let error = null;
+    try {
+        if (!existsSync(changeDir)) {
+            mkdirSync(changeDir, { recursive: true });
+        }
+        const markerPath = join(changeDir, canonicalSessionId);
+        let existingNames = [];
+        try {
+            existingNames = readdirSync(changeDir);
+        }
+        catch {
+            existingNames = [];
+        }
+        for (const name of existingNames) {
+            if (name === canonicalSessionId)
+                continue;
+            const stale = join(changeDir, name);
+            try {
+                rmSync(stale, { recursive: true, force: true });
+                removed.push(name);
+            }
+            catch (e) {
+                // Best-effort: a single un-deletable entry must not abort the
+                // sync (the caller gets the rest of the diff).
+                error = e instanceof Error ? e.message : String(e);
+            }
+        }
+        if (!existsSync(markerPath)) {
+            mkdirSync(markerPath, { recursive: true });
+            created = canonicalSessionId;
+        }
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+    }
+    return { removed, created, error };
+}
 /**
  * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
  *
@@ -402,6 +497,89 @@ function copyDirRecursiveSync(src, dest) {
         }
     }
 }
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/<sid>/system/subagent-progress.json`
+ *   - `.peaks/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export function migrateSubAgentState(projectRoot) {
+    const root = resolve(projectRoot);
+    const newDir = join(root, '.peaks', SUB_AGENTS_DIR);
+    const migratedFiles = [];
+    const errors = [];
+    for (const session of discoverSessions(projectRoot)) {
+        const oldSystemDir = join(session.path, 'system');
+        if (!existsSync(oldSystemDir))
+            continue;
+        const newSessionDir = join(newDir, session.sessionId);
+        mkdirSync(newSessionDir, { recursive: true });
+        for (const fname of SUB_AGENT_MIGRATION_FILES) {
+            const oldPath = join(oldSystemDir, fname);
+            const newPath = join(newSessionDir, fname);
+            if (!existsSync(oldPath))
+                continue;
+            if (existsSync(newPath)) {
+                // New path is authoritative; remove stale old file.
+                try {
+                    rmSync(oldPath, { force: true });
+                }
+                catch { /* best effort */ }
+                continue;
+            }
+            try {
+                try {
+                    renameSync(oldPath, newPath);
+                }
+                catch (renameError) {
+                    // Cross-device or locked-file fallback: copy + unlink.
+                    copyFileSync(oldPath, newPath);
+                    unlinkSync(oldPath);
+                }
+                migratedFiles.push(join('.peaks', session.sessionId, 'system', fname));
+            }
+            catch (error) {
+                errors.push({
+                    path: oldPath,
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        // R-2 guard: only remove the legacy system/ dir when it has zero
+        // remaining files (the user might have unrelated content there).
+        try {
+            const remaining = readdirSync(oldSystemDir);
+            if (remaining.length === 0) {
+                rmdirSync(oldSystemDir);
+            }
+        }
+        catch { /* best effort */ }
+    }
+    return { migratedFiles, errors };
+}
 /**
  * Top-level orchestrator. Wires migration (added in slice
  * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,
@@ -417,11 +595,19 @@ export function reconcileWorkspace(options) {
     // before that read means the new path is the only path observed by
     // `getSessionIdCanonical` after this call returns.
     const migration = migrateOldRuntimeState(projectRoot);
-    const migrateErrors = migration.errors.map((e) => ({
-        kind: 'migrate',
-        path: e.path,
-        message: e.message
-    }));
+    const subAgentMigration = migrateSubAgentState(projectRoot);
+    const migrateErrors = [
+        ...migration.errors.map((e) => ({
+            kind: 'migrate',
+            path: e.path,
+            message: e.message
+        })),
+        ...subAgentMigration.errors.map((e) => ({
+            kind: 'migrate',
+            path: e.path,
+            message: e.message
+        }))
+    ];
     const sessions = discoverSessions(projectRoot);
     const activeSkillSessionId = readActiveSkillSessionId(projectRoot);
     const canonical = pickCanonicalSession(sessions, activeSkillSessionId);
@@ -445,6 +631,36 @@ export function reconcileWorkspace(options) {
     }
     const deletionCandidates = findDeletionCandidates(sessions, ageThresholdMs);
     const deletionResult = applyDeletions(deletionCandidates, apply);
+    // Slice 006: sync the single `change/<canonicalSessionId>/` live
+    // marker (replaces the F3 per-change-id symlink layer). The marker
+    // is an empty dir; the function removes every other entry under
+    // `.peaks/_runtime/change/`. Idempotent. This step is independent
+    // of the apply flag — syncing the marker is a derived-state write,
+    // not a destructive side effect.
+    const changeMarker = canonical === null
+        ? { removed: [], created: null, error: 'no canonical session' }
+        : syncChangeMarker(projectRoot, canonical.sessionId);
+    // Slice 006: clean up the F3-introduced `.peaks/_runtime/<sid>/system/`
+    // subdir under EVERY session dir (not just the canonical one). The
+    // subdir was created eagerly by `initWorkspace` (F3) but was never
+    // used. The cleanup is idempotent: re-running on a tree without the
+    // subdir is a no-op. We walk every discovered session, not just the
+    // canonical one, because the user has 6 F3 sessions with the cruft
+    // and the spec says all of them must be removed. Logged in the
+    // systemCleaned array.
+    const systemCleaned = [];
+    for (const session of sessions) {
+        const systemDir = join(session.path, 'system');
+        if (existsSync(systemDir)) {
+            try {
+                rmSync(systemDir, { recursive: true, force: true });
+                systemCleaned.push(systemDir);
+            }
+            catch {
+                // Best-effort: a locked subdir does not block the rest of reconcile.
+            }
+        }
+    }
     return {
         projectRoot,
         sessions,
@@ -459,6 +675,9 @@ export function reconcileWorkspace(options) {
         apply,
         repointed,
         migratedFiles: migration.migratedFiles,
-        errors: [...migrateErrors, ...deletionResult.errors]
+        subAgentStateMigrated: subAgentMigration.migratedFiles.length,
+        errors: [...migrateErrors, ...deletionResult.errors],
+        changeMarker,
+        systemCleaned
     };
 }

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

@@ -65,6 +65,18 @@ export type ReconcileResult = {
      * consumers can ignore this field.
      */
     migratedFiles: string[];
+    /**
+     * Count of legacy per-session sub-agent state files moved from
+     * `.peaks/<sid>/system/{subagent-progress,progress-spawn}.json` into
+     * `.peaks/_sub_agents/<sid>/` during this reconcile run.
+     *
+     * Added in slice 2026-06-06-sub-agent-spawn-bug-and-decouple. The
+     * detailed list of moved files is not surfaced here (the count is
+     * what the CLI summary and QA test assert on); the underlying
+     * `migrateSubAgentState` helper returns the full path list for
+     * forensics. Additive — older consumers can ignore this field.
+     */
+    subAgentStateMigrated: number;
     /**
      * Errors encountered during the migration step. Each entry has a
      * `kind: 'migrate'` discriminator so consumers can tell migration
@@ -78,6 +90,31 @@ export type ReconcileResult = {
         path: string;
         message: string;
     }>;
+    /**
+     * Slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs):
+     * result of syncing the single `change/<canonicalSessionId>/` live
+     * marker under `.peaks/_runtime/change/`. The marker is an empty
+     * directory; every other entry under `change/` is removed. The
+     * `removed` array lists entry names that were deleted (e.g.
+     * `['<oldSid>/']`); `created` is the name of the new marker (or
+     * `null` when the canonical marker already existed — no-op);
+     * `error` is the first error message (if any) encountered during
+     * the sync. Additive — older consumers can ignore this field.
+     * Replaces the F3 `changeLinks` field.
+     */
+    changeMarker: {
+        removed: string[];
+        created: string | null;
+        error: string | null;
+    };
+    /**
+     * Slice 006: list of absolute paths to `.peaks/_runtime/<sid>/system/`
+     * subdirs that were removed by this reconcile run. The F3
+     * `initWorkspace` eagerly created the `system/` subdir; slice 006
+     * deletes it during reconcile. Empty when the canonical session
+     * had no `system/` subdir. Additive.
+     */
+    systemCleaned: string[];
 };
 export type ReconcileOptions = {
     projectRoot: string;

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

@@ -1,36 +1,8 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory } from '../../shared/fs.js';
-import { getSessionId, setCurrentSessionBinding } from '../session/session-manager.js';
+import { getSessionId, setCurrentSessionBinding, setSessionMeta } from '../session/session-manager.js';
 import { setCurrentChangeId } from '../../shared/change-id.js';
-/**
- * Per-slice subdirectories created **inside the change-id dir**
- * (`.peaks/<change-id>/...`). These are the reviewable
- * artifacts and are tracked in git. The `system/` subdir is
- * intentionally NOT in this list — it lives under the session
- * dir (`.peaks/_runtime/<session-id>/system/`), since it holds
- * live sub-agent progress and spawn records, which are ephemeral.
- */
-const CHANGE_ARTIFACT_SUBDIRECTORIES = [
-    'prd/source',
-    'prd/requests',
-    'ui/requests',
-    'rd/requests',
-    'qa/test-cases',
-    'qa/test-reports',
-    'qa/requests',
-    'qa/screenshots',
-    'sc',
-    'txt'
-];
-/**
- * Per-session subdirectories created **inside the session dir**
- * (`.peaks/_runtime/<session-id>/...`). These are the ephemeral
- * state and are gitignored.
- */
-const SESSION_EPHEMERAL_SUBDIRECTORIES = [
-    'system'
-];
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
 const PROHIBITED_SUFFIXES = ['session', 'work', 'task', 'test', 'temp', 'tmp'];
 // Auto-generated session ID pattern: YYYY-MM-DD-session-<6位hex>
@@ -77,14 +49,21 @@ export function validateSessionId(sessionId) {
 }
 export async function initWorkspace(options) {
     validateSessionId(options.sessionId);
-    // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work):
-    //   - Reviewable artifacts (rd/, qa/, prd/, txt/) are created at
+    // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work) +
+    // slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs):
+    //   - Reviewable artifacts (rd/, qa/, prd/, txt/) live at
     //     `.peaks/<change-id>/<role>/` (tracked in git) when a change-id
-    //     is given. This is the canonical home for cross-session content.
+    //     is given. The role subdirs are NOT pre-created — the writer
+    //     (e.g. `peaks request init`, `peaks rd`) creates the parent
+    //     dirs on demand via `mkdirSync(..., { recursive: true })`.
     //   - The session dir `.peaks/_runtime/<session-id>/` (gitignored)
-    //     holds only ephemeral state — currently `system/` (live
-    //     sub-agent progress + spawn records). The session id remains
-    //     the binding for that ephemeral state.
+    //     now holds ONLY the canonical `session.json` metadata. The
+    //     F3-introduced `system/` subdir is gone — slice 006 removes
+    //     it via `peaks workspace reconcile`; new init calls do not
+    //     pre-create it.
+    //   - The change-id dir is created when `--change-id` is given,
+    //     but its role subdirs (prd/, qa/, rd/, sc/, txt/) are NOT
+    //     pre-created either — same lazy-mkdir rule.
     //
     // The CLI accepts `--change-id <id>` to bind the change. The legacy
     // session-scoped layout (`.peaks/<session-id>/<role>/<file>`) is
@@ -95,8 +74,8 @@ export async function initWorkspace(options) {
     const created = [];
     const alreadyExisted = [];
     // 1. Create the session dir (canonical location `.peaks/_runtime/<sid>/`)
-    //    with ONLY ephemeral subdirs (`system/`). The session dir is
-    //    gitignored.
+    //    with NO subdirs. The session dir is gitignored; the role
+    //    subdirs and the `system/` subdir are gone entirely (slice 006).
     if (await isDirectory(sessionRoot)) {
         alreadyExisted.push('.');
     }
@@ -104,22 +83,20 @@ export async function initWorkspace(options) {
         await mkdir(sessionRoot, { recursive: true });
         created.push('.');
     }
-    for (const sub of SESSION_EPHEMERAL_SUBDIRECTORIES) {
-        const full = join(sessionRoot, sub);
-        if (await isDirectory(full)) {
-            alreadyExisted.push(sub);
-        }
-        else {
-            await mkdir(full, { recursive: true });
-            created.push(sub);
-        }
-    }
+    // 1a. Write the per-session metadata file. Slice 006 makes
+    //     `.peaks/_runtime/<sid>/session.json` the durable session
+    //     metadata (the body's source of truth, the `peaks workspace
+    //     reconcile` discovery source). The file is created on first
+    //     init and refreshed on every subsequent init. Idempotent.
+    setSessionMeta(options.projectRoot, options.sessionId, {});
     // 2. If a change-id is given, also create the change-id dir at
-    //    `.peaks/<change-id>/` (tracked) with the reviewable subdirs.
-    //    When the caller did NOT specify a change-id, this step is
-    //    skipped — reviewable writes for this session are then blocked
-    //    until a change-id is bound (or the user re-runs init with
-    //    `--change-id`). Surfaces in `changeIdAction: 'none'`.
+    //    `.peaks/<change-id>/` (tracked) with NO role subdirs. The
+    //    role subdirs (prd/, qa/, rd/, sc/, txt/) are created on demand
+    //    by the writer at the write site. When the caller did NOT
+    //    specify a change-id, this step is skipped — reviewable writes
+    //    for this session are then blocked until a change-id is bound
+    //    (or the user re-runs init with `--change-id`). Surfaces in
+    //    `changeIdAction: 'none'`.
     let resolvedChangeId = null;
     let changeIdAction = 'none';
     if (options.changeId !== undefined && options.changeId.length > 0) {
@@ -132,16 +109,6 @@ export async function initWorkspace(options) {
             await mkdir(changeDir, { recursive: true });
             created.push(resolvedChangeId);
         }
-        for (const sub of CHANGE_ARTIFACT_SUBDIRECTORIES) {
-            const full = join(changeDir, sub);
-            if (await isDirectory(full)) {
-                alreadyExisted.push(sub);
-            }
-            else {
-                await mkdir(full, { recursive: true });
-                created.push(sub);
-            }
-        }
         // 3. Bind the change-id so RD/QA/PRD services know where to write
         //    reviewable artifacts. The binding is a symlink at
         //    `.peaks/_runtime/current-change` pointing at the change-id dir.

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.1";
+export declare const CLI_VERSION = "1.3.3";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.1";
+export const CLI_VERSION = "1.3.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -56,6 +56,7 @@
     "@colbymchenry/codegraph": "0.7.10",
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
+    "headroom-ai": "0.22.4",
     "ora": "^8.2.0",
     "shadcn": "4.7.0",
     "terminal-kit": "^3.1.2"