peaks-cli 1.0.24 → 1.0.26

package/dist/src/cli/commands/core-artifact-commands.js

@@ -8,6 +8,7 @@ import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
+import { ensureSession, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isArtifactProvider, isArtifactSetupStep, printResult } from '../cli-helpers.js';
 export function registerCoreAndArtifactCommands(program, io) {
@@ -71,13 +72,21 @@ export function registerCoreAndArtifactCommands(program, io) {
         .command('presence:set <name>')
         .description('Set the currently active Peaks skill for session-wide visibility')
         .option('--mode <mode>', 'execution mode')
-        .option('--gate <gate>', 'current gate')).action((name, options) => {
+        .option('--gate <gate>', 'current gate')).action(async (name, options) => {
         if (options.mode !== undefined && !isSkillPresenceMode(options.mode)) {
             printResult(io, fail('skill.presence:set', 'INVALID_MODE', `Invalid mode: ${options.mode} (expected one of: full-auto, assisted, swarm, strict)`, { name, mode: options.mode }, ['Use a valid mode: full-auto, assisted, swarm, or strict']), options.json);
             process.exitCode = 1;
             return;
         }
         const presence = setSkillPresence(name, options.mode, options.gate);
+        // Also update session metadata so session dirs self-document
+        const projectRoot = process.cwd();
+        const sessionId = await ensureSession(projectRoot);
+        setSessionMeta(projectRoot, sessionId, {
+            skill: name,
+            ...(options.mode ? { mode: options.mode } : {}),
+            ...(options.gate ? { gate: options.gate } : {})
+        });
         printResult(io, ok('skill.presence:set', { active: true, ...presence }), options.json);
     });
     addJsonOption(skill
@@ -116,6 +125,39 @@ export function registerCoreAndArtifactCommands(program, io) {
             lastHeartbeat: updated.lastHeartbeat
         }), options.json);
     });
+    const session = program.command('session').description('Manage Peaks session directories');
+    addJsonOption(session
+        .command('list')
+        .description('List all session directories with titles and metadata')).action((options) => {
+        const projectRoot = process.cwd();
+        const metas = listSessionMetas(projectRoot);
+        printResult(io, ok('session.list', { sessions: metas, total: metas.length }), options.json);
+    });
+    addJsonOption(session
+        .command('info <sessionId>')
+        .description('Show full metadata for a session directory')).action((sessionId, options) => {
+        const projectRoot = process.cwd();
+        const meta = getSessionMeta(projectRoot, sessionId);
+        if (meta === null) {
+            printResult(io, fail('session.info', 'SESSION_NOT_FOUND', `Session "${sessionId}" not found or has no metadata`, { sessionId }, ['Use `peaks session list` to see available sessions']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('session.info', meta), options.json);
+    });
+    addJsonOption(session
+        .command('title <sessionId> <title>')
+        .description('Set a human-readable title for a session directory')).action((sessionId, title, options) => {
+        const projectRoot = process.cwd();
+        try {
+            const meta = setSessionTitle(projectRoot, sessionId, title);
+            printResult(io, ok('session.title', meta), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('session.title', 'SESSION_TITLE_FAILED', getErrorMessage(error), { sessionId }, ['Verify the sessionId exists under .peaks/']), options.json);
+            process.exitCode = 1;
+        }
+    });
     const profile = program.command('profile').description('Manage runtime profiles');
     addJsonOption(profile.command('list').description('List available profiles')).action((options) => {
         printResult(io, ok('profile.list', { profiles: listProfiles() }), options.json);

package/dist/src/services/session/index.d.ts

@@ -1 +1 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getProjectScanPath, hasProjectScan, type SessionInfo } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, type SessionInfo, type SessionMeta } from './session-manager.js';

package/dist/src/services/session/index.js

@@ -1 +1 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getProjectScanPath, hasProjectScan } from './session-manager.js';
+export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan } from './session-manager.js';

package/dist/src/services/session/session-manager.d.ts

@@ -10,6 +10,35 @@ export type SessionInfo = {
     createdAt: string;
     projectRoot: string;
 };
+export type SessionMeta = {
+    sessionId: string;
+    title?: string;
+    skill?: string;
+    mode?: string;
+    gate?: string;
+    createdAt: string;
+    lastActivity?: string;
+    projectRoot: string;
+};
+/**
+ * Read metadata for a specific session directory.
+ * Returns null if the session directory or its session.json does not exist.
+ */
+export declare function getSessionMeta(projectRoot: string, sessionId: string): SessionMeta | null;
+/**
+ * Write or update metadata for a session.  Fields besides sessionId and createdAt
+ * are merged on top of the current meta (partial update).
+ */
+export declare function setSessionMeta(projectRoot: string, sessionId: string, partial: Partial<Omit<SessionMeta, 'sessionId' | 'createdAt' | 'projectRoot'>>): SessionMeta;
+/**
+ * Set the display title for a session directory.
+ */
+export declare function setSessionTitle(projectRoot: string, sessionId: string, title: string): SessionMeta;
+/**
+ * List all session directories under .peaks with their metadata.
+ * Returns sessions sorted by sessionId descending (most recent first).
+ */
+export declare function listSessionMetas(projectRoot: string): SessionMeta[];
 /**
  * Get or create the current session for a project.
  * If a valid session already exists, returns it.

package/dist/src/services/session/session-manager.js

@@ -5,11 +5,12 @@
  * Sessions are automatically created when any skill is invoked.
  * Each session gets a unique directory under .peaks/ with incrementing numbered files.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
 const SESSION_FILE = '.session.json';
+const META_FILE = 'session.json';
 /**
  * Generate a new session ID.
  * Format: YYYY-MM-DD-session-<6位hex>
@@ -60,6 +61,86 @@ function writeSessionFile(projectRoot, info) {
     }
     writeFileSync(sessionFile, JSON.stringify(info, null, 2), 'utf8');
 }
+function getMetaFilePath(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', sessionId, META_FILE);
+}
+function readSessionMeta(projectRoot, sessionId) {
+    const metaPath = getMetaFilePath(projectRoot, sessionId);
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const raw = readFileSync(metaPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId !== 'string' || parsed.sessionId.length === 0) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeSessionMeta(projectRoot, sessionId, meta) {
+    const metaPath = getMetaFilePath(projectRoot, sessionId);
+    const metaDir = join(projectRoot, '.peaks', sessionId);
+    if (!existsSync(metaDir)) {
+        mkdirSync(metaDir, { recursive: true });
+    }
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2), 'utf8');
+}
+/**
+ * Read metadata for a specific session directory.
+ * Returns null if the session directory or its session.json does not exist.
+ */
+export function getSessionMeta(projectRoot, sessionId) {
+    return readSessionMeta(projectRoot, sessionId);
+}
+/**
+ * Write or update metadata for a session.  Fields besides sessionId and createdAt
+ * are merged on top of the current meta (partial update).
+ */
+export function setSessionMeta(projectRoot, sessionId, partial) {
+    const existing = readSessionMeta(projectRoot, sessionId);
+    const now = new Date().toISOString();
+    const meta = existing
+        ? { ...existing, ...partial, lastActivity: now }
+        : {
+            sessionId,
+            projectRoot,
+            createdAt: now,
+            ...partial,
+            lastActivity: now
+        };
+    writeSessionMeta(projectRoot, sessionId, meta);
+    return meta;
+}
+/**
+ * Set the display title for a session directory.
+ */
+export function setSessionTitle(projectRoot, sessionId, title) {
+    return setSessionMeta(projectRoot, sessionId, { title });
+}
+/**
+ * List all session directories under .peaks with their metadata.
+ * Returns sessions sorted by sessionId descending (most recent first).
+ */
+export function listSessionMetas(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const entries = readdirSync(peaksRoot, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isDirectory() && /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(entry.name))
+        .map((entry) => {
+        const meta = readSessionMeta(projectRoot, entry.name);
+        return meta ?? {
+            sessionId: entry.name,
+            projectRoot,
+            createdAt: ''
+        };
+    })
+        .sort((a, b) => b.sessionId.localeCompare(a.sessionId));
+}
 /**
  * Get or create the current session for a project.
  * If a valid session already exists, returns it.
@@ -74,13 +155,20 @@ export async function ensureSession(projectRoot) {
         return existing.sessionId;
     }
     const sessionId = generateSessionId();
+    const now = new Date().toISOString();
     const info = {
         sessionId,
-        createdAt: new Date().toISOString(),
+        createdAt: now,
         projectRoot
     };
     writeSessionFile(projectRoot, info);
     await initWorkspace({ projectRoot, sessionId });
+    // Initialize session metadata inside the session directory
+    writeSessionMeta(projectRoot, sessionId, {
+        sessionId,
+        projectRoot,
+        createdAt: now
+    });
     return sessionId;
 }
 /**

package/dist/src/services/skills/skill-presence-service.d.ts

@@ -5,6 +5,7 @@ export type SkillPresence = {
     skill: string;
     mode?: SkillPresenceMode;
     gate?: string;
+    sessionId?: string;
     setAt: string;
     lastHeartbeat?: string;
 };

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

@@ -10,19 +10,36 @@ export function isSkillPresenceMode(value) {
     return VALID_SKILL_PRESENCE_MODES.includes(value);
 }
 const PRESENCE_FILE = '.peaks/.active-skill.json';
+const SESSION_FILE = '.peaks/.session.json';
 function resolvePresencePath() {
     return resolve(process.cwd(), PRESENCE_FILE);
 }
+function getCurrentSessionId() {
+    const sessionPath = resolve(process.cwd(), SESSION_FILE);
+    if (!existsSync(sessionPath))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(sessionPath, 'utf8'));
+        return typeof data.sessionId === 'string' && data.sessionId.length > 0
+            ? data.sessionId
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function exportSkillPresence() {
     return resolvePresencePath();
 }
 export function setSkillPresence(skill, mode, gate) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
+    const sessionId = getCurrentSessionId();
     const now = new Date().toISOString();
     const presence = {
         skill,
         ...(validatedMode ? { mode: validatedMode } : {}),
         ...(gate ? { gate } : {}),
+        ...(sessionId ? { sessionId } : {}),
         setAt: now,
         lastHeartbeat: now
     };
@@ -45,6 +62,13 @@ export function getSkillPresence() {
         if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
             return null;
         }
+        if (typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0) {
+            const currentSessionId = getCurrentSessionId();
+            if (currentSessionId && parsed.sessionId !== currentSessionId) {
+                unlinkSync(presencePath);
+                return null;
+            }
+        }
         return parsed;
     }
     catch {
@@ -62,6 +86,13 @@ export function touchSkillHeartbeat() {
         if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
             return null;
         }
+        if (typeof parsed.sessionId === 'string' && parsed.sessionId.length > 0) {
+            const currentSessionId = getCurrentSessionId();
+            if (currentSessionId && parsed.sessionId !== currentSessionId) {
+                unlinkSync(presencePath);
+                return null;
+            }
+        }
         parsed.lastHeartbeat = new Date().toISOString();
         writeFileSync(presencePath, JSON.stringify(parsed, null, 2), 'utf8');
         return parsed;

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.24";
+export declare const CLI_VERSION = "1.0.26";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.24";
+export const CLI_VERSION = "1.0.26";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-solo/SKILL.md

@@ -78,6 +78,16 @@ Then display the compact status header: `Peaks-Cli Skill: peaks-solo | Peaks-Cli
 
 Update with `peaks skill presence:set peaks-solo --mode <mode> --gate <gate>` when gates change. The presence file persists across the full workflow lifecycle — do NOT clear it at workflow end.
 
+### Peaks-Cli Step 2.5: Set session title
+
+Extract a short (8-20 Chinese characters, or 4-10 English words) descriptive title from the user's first request. The title should capture the core task — e.g. "修复登录页OAuth回调异常", "添加暗色模式开关", "搭建项目基础架构". Then run:
+
+```bash
+peaks session title $(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])") "<title>"
+```
+
+If the session directory already has a title (check via `peaks session list --json`), skip this step — the title is already set.
+
 ## Boundaries
 
 Peaks-Cli Solo may:
@@ -566,6 +576,14 @@ After `peaks-rd` finishes any implementation, repair, or code-output slice, Peak
 
 Solo is itself a skill running in the current session. To "invoke peaks-rd" or "peaks-qa", Solo MUST use the `Skill` tool with the role's name (e.g. `Skill(skill="peaks-rd")` or `Skill(skill="peaks-qa")`), passing the `<request-id>` and `<session-id>` as arguments so the role reads the same artifacts Solo wrote. Do NOT re-implement the role's logic inline in Solo. Do NOT use the `Agent` tool with a sub-agent — role skills are skills, not agents. After the role skill returns, Solo reads the artifacts the role wrote (via the request artifact path or `peaks request show <rid> --role <role>`) to decide the next step.
 
+**Presence restoration after role skill returns (MANDATORY):** Role skills (peaks-rd, peaks-qa, peaks-ui) call `peaks skill presence:set <role>` internally, which overwrites `.peaks/.active-skill.json`. After EVERY role skill returns — whether success, repair-needed, or failure — Solo MUST immediately restore the orchestrator presence by re-running the same presence command from Step 2:
+
+```bash
+peaks skill presence:set peaks-solo --mode <mode> --gate <current-gate>
+```
+
+This keeps the CLAUDE.md status header accurate (`Peaks-Cli Skill: peaks-solo`) instead of showing a stale role name. Use the current mode and gate values; the gate may have advanced since startup. Skipping this step causes the header to display the last role skill name permanently.
+
 **Full-auto auto-proceed rule**: In the `full-auto` profile, when RD transitions to `qa-handoff`, Solo immediately invokes `peaks-qa` via the Skill tool with the same `<request-id>`. Do not pause, do not ask the user, do not summarize RD results as if they were final. The only valid reason to skip QA is when `--type` is `docs` or `chore` (no acceptance surface).
 
 A QA report with any failing, blocked, missing, or unverified acceptance item is not a pass.
@@ -586,12 +604,16 @@ When `peaks-qa` returns `verdict=return-to-rd`, Solo does NOT manually rewrite R
 4. peaks-rd fixes the reported issues only (red-line scope: do not modify unrelated surfaces), regenerates code-review and security-review evidence if changes touched reviewed surfaces, then transitions `rd → implemented → qa-handoff` again.
 5. Solo invokes `peaks-qa` again with the same `<request-id>` (the same Skill call as before). QA re-runs gates against the new diff.
 6. Repeat steps 1-5 until QA returns `verdict=pass`, or the cap below fires.
+   **After each repair iteration** (after peaks-rd and peaks-qa both return), Solo MUST restore presence:
+   ```bash
+   peaks skill presence:set peaks-solo --mode <mode> --gate repair-cycle-<N>
+   ```
 
 **Repair cycle cap**: After 3 repair cycles without a passing QA verdict, emit a blocked TXT handoff regardless of remaining issues. Do not loop indefinitely. If a specific issue cannot be resolved within 3 cycles, mark it as a known blocker in the TXT handoff and proceed to the SC phase.
 
 In full-auto mode, treat the RD↔QA repair loop as a built-in controller objective: loop through RD→QA until all acceptance items pass (max 3 cycles). Do not exit the loop on a non-passing QA verdict unless the TXT handoff marks the workflow as blocked.
 
-## Peaks-Cli Default runbook
+## Default runbook
 
 > **Maintenance**: The numbered workflow list above (steps 0-11) is the canonical phase sequence. This runbook is the executable CLI transcription. When updating this skill, keep both in lockstep — a change to one must be reflected in the other.
 
@@ -765,7 +787,7 @@ Do NOT call `peaks skill presence:clear` at workflow end. The presence file and
 
 **Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.
 
-## Peaks-Cli Codegraph orchestration context
+## Codegraph orchestration context
 
 Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Solo must not treat codegraph output as approval for scope, design, or QA verdict.