peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,300 @@
+import { runDoctor } from '../../../services/doctor/doctor-service.js';
+import { listSkills } from '../../../services/skills/skill-registry.js';
+import { runSkillSync, SYNC_PLATFORMS } from '../../../services/skills/sync-service.js';
+import { inspectSkillRunbook } from '../../../services/skills/skill-runbook-service.js';
+import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat, checkStalePresence } from '../../../services/skills/skill-presence-service.js';
+import { detectPresenceMarker } from '../../../services/hooks/presence-marker-detector.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { generateProjectContext } from '../../../services/memory/project-context-service.js';
+import { getSessionId, setSessionMeta } from '../../../services/session/session-manager.js';
+import { fail, ok } from '../../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+// Slice S0 (4.0.0-beta.5 peaks-solo dispatcher release):
+// `peaks skill search` is the CLI primitive that feeds the
+// peaks-solo dispatcher (S1). Adding a single import + register call
+// here keeps the change surgical and leaves all existing skill
+// subcommands (list / doctor / sync / runbook / presence / heartbeat)
+// untouched. See
+// docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+// and the S0 plan under docs/superpowers/plans/.
+import { registerSkillSearchCommand } from '../skill-search-commands.js';
+export function registerSkillCommand(program, io) {
+    const skill = program.command('skill').description('Manage Peaks skills');
+    addJsonOption(skill.command('list').description('List skills derived from skills/*/SKILL.md')).action(async (options) => {
+        const skills = await listSkills();
+        if (options.json === true) {
+            printResult(io, ok('skill.list', { skills }), true);
+        }
+        else {
+            const sorted = [...skills].sort((a, b) => {
+                // Slice S0 (4.0.0-beta.5): peaks-solo is the dispatcher (front
+                // door) — list it FIRST so users discover the dispatcher before
+                // any specific leaf. Followed by peaks-sop (current default
+                // runbook showcase) and peaks-code (canonical code-domain
+                // orchestrator); everything else falls back to alphabetical.
+                if (a.name === 'peaks-solo')
+                    return -1;
+                if (b.name === 'peaks-solo')
+                    return 1;
+                if (a.name === 'peaks-sop')
+                    return -1;
+                if (b.name === 'peaks-sop')
+                    return 1;
+                if (a.name === 'peaks-code')
+                    return -1;
+                if (b.name === 'peaks-code')
+                    return 1;
+                return a.name.localeCompare(b.name);
+            });
+            for (const skill of sorted) {
+                io.stdout(`  ${skill.name.padEnd(14)}${skill.description}`);
+            }
+            io.stdout(`\n  Invoke any skill by typing its name in conversation (e.g. \`peaks-sop\`).`);
+        }
+    });
+    addJsonOption(skill.command('doctor').description('Run skill-related doctor checks')).action(async (options) => {
+        const report = await runDoctor();
+        const skillChecks = report.checks.filter((check) => check.id.startsWith('skill'));
+        const failed = skillChecks.filter((check) => !check.ok).length;
+        if (options.json === true) {
+            printResult(io, ok('skill.doctor', { checks: skillChecks, ok: failed === 0 }), true);
+        }
+        else {
+            for (const check of skillChecks) {
+                const icon = check.ok ? '+' : '×';
+                io.stdout(`  ${icon}  ${check.message}`);
+            }
+            io.stdout(`\n  ${skillChecks.length - failed} passed, ${failed} failed`);
+            if (failed > 0) {
+                io.stderr('\nOne or more skill checks failed.');
+            }
+        }
+        if (failed > 0) {
+            process.exitCode = 1;
+        }
+    });
+    // Slice #12 final piece (per spec §9 line 1105):
+    // `peaks skills sync 8 平台分发`. Idempotent: re-running is a
+    // no-op when the symlinks are already correct.
+    addJsonOption(skill
+        .command('sync')
+        .description(`Sync the peaks-* skill family to one or all of the 8 supported LLM-CLI platforms (${SYNC_PLATFORMS.join(', ')}). Idempotent.`)
+        .option('--platform <id>', `sync only one platform (default: --all). Valid: ${SYNC_PLATFORMS.join(', ')}`)
+        .option('--all', 'sync all 8 platforms (default if --platform is omitted)')
+        .option('--dry-run', 'do not write; emit the same shape with applied=false')
+        .option('--project <path>', 'project root (default: cwd)')).action(async (options) => {
+        try {
+            const projectRoot = options.project ?? process.cwd();
+            const platforms = options.platform !== undefined ? [options.platform] : undefined;
+            const result = await runSkillSync({
+                projectRoot,
+                ...(platforms !== undefined ? { platforms } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+            });
+            const envelope = ok('skill.sync', result, [], [
+                `syncedCount: ${result.syncedCount}/${result.perPlatform.length} platforms`,
+                `totalInstalled: ${result.totalInstalled} skill symlinks`,
+                result.failedCount > 0
+                    ? `failedCount: ${result.failedCount} (run \`peaks skill status\` for details)`
+                    : 'no failures',
+            ]);
+            printResult(io, envelope, options.json);
+            if (result.failedCount > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('skill.sync', 'SKILL_SYNC_FAILED', message, { applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(skill
+        .command('runbook <name>')
+        .description('Inspect a skill Default runbook section and its --apply authorization-note status')).action(async (name, options) => {
+        try {
+            const inspection = await inspectSkillRunbook(name);
+            const result = inspection.ok
+                ? ok('skill.runbook', inspection)
+                : fail('skill.runbook', inspection.hasRunbook ? 'SKILL_RUNBOOK_APPLY_UNGATED' : 'SKILL_RUNBOOK_MISSING', inspection.hasRunbook
+                    ? `Skill ${inspection.name} has ${inspection.destructiveApplyLines.length} destructive --apply command(s) without an authorization/dry-run note`
+                    : `Skill ${inspection.name} is missing a ## Default runbook section`, inspection, inspection.hasRunbook
+                    ? ['Add an authorization or --dry-run note next to destructive --apply lines in the runbook section']
+                    : ['Add a `## Default runbook` section to the skill SKILL.md']);
+            printResult(io, result, options.json);
+            if (!inspection.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('skill.runbook', 'SKILL_NOT_FOUND', getErrorMessage(error), { name }), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(skill
+        .command('presence')
+        .description('Show the currently active Peaks skill (alias: presence:get)')
+        .option('--check-stale', 'slice 002 (v2.15.0): also report whether the recorded outer session id still matches the current one. Default false (back-compat).')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
+        const presence = getSkillPresence(options.project);
+        if (presence === null) {
+            printResult(io, ok('skill.presence', { active: false }), options.json);
+            return;
+        }
+        if (options.checkStale === true) {
+            // Slice 002 (v2.15.0) AC-1: pair the read with a staleness
+            // check so callers (peaks-code Step 1, statusline) get both
+            // pieces of info from a single CLI invocation. The presence
+            // is returned UNCHANGED — `--check-stale` is a read-only flag,
+            // not a clear.
+            const staleness = checkStalePresence({ projectRootOverride: options.project });
+            printResult(io, ok('skill.presence', {
+                active: true,
+                ...presence,
+                stale: staleness.stale,
+                staleReason: staleness.reason,
+                currentOuterSessionId: staleness.currentOuterSessionId,
+                recordedOuterSessionId: staleness.recordedOuterSessionId
+            }), options.json);
+            return;
+        }
+        printResult(io, ok('skill.presence', { active: true, ...presence }), options.json);
+    });
+    addJsonOption(skill
+        .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')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((name, options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        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, options.project);
+        // As of slice 003-2026-06-06-session-layout-canonicalize we do NOT
+        // call `ensureSession` here. The CLI wrapper previously spawned a
+        // new session on every presence call, which made the canonical
+        // session binding drift (the LLM saw the session id change every
+        // turn). The presence now reuses the session bound at
+        // `.peaks/_runtime/session.json` (or the legacy `.peaks/.session.json`
+        // during the back-compat window). If no session is bound, the
+        // presence still writes the active-skill marker — downstream code
+        // can `peaks workspace init` separately to create the session.
+        //
+        // Session metadata is updated when a session is bound (read-only
+        // path: `getSessionId`). We do not auto-spawn a session.
+        const boundSessionId = getSessionId(projectRoot);
+        if (boundSessionId !== null) {
+            setSessionMeta(projectRoot, boundSessionId, {
+                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
+        .command('presence:clear')
+        .description('Clear the active Peaks skill presence indicator and update project context')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const removed = clearSkillPresence(options.project);
+        // Auto-update project context so future sessions have up-to-date history.
+        // Slice 2026-07-15-project-scan-bootstrap: generateProjectContext now also
+        // bootstraps `.peaks/project-scan/` (idempotent). Await the async
+        // signature; failure is still non-fatal so we don't block the clear.
+        try {
+            await generateProjectContext(projectRoot);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // non-fatal: context update failure should not block presence clear
+        }
+        printResult(io, ok('skill.presence:clear', { active: false, removed, projectContextUpdated: true }), options.json);
+    });
+    // Slice 002 (v2.15.0) — AC-1: presence staleness detector.
+    // peaks-code Step 1 (and `peaks code should-pause --step
+    // step-1-mode-select`) calls this to decide whether the recorded
+    // `mode` field can be trusted or whether the LLM must AskUserQuestion.
+    addJsonOption(skill
+        .command('presence:check-stale')
+        .description('Slice 002 (v2.15.0) AC-1: report whether the recorded presence outer session id still matches the current outer session id. ' +
+        'Returns { stale: boolean, reason: "outer-session-mismatch" | "no-presence" | null }. ' +
+        'Pure read-only — does NOT clear the presence (use `peaks skill presence:clear` for that).')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--current-outer <id>', 'override the current outer session id (test seam; default: read from PEAKS_OUTER_SESSION_ID / CLAUDE_CODE_SESSION_ID)')).action((options) => {
+        // v2.15.0 slice 002 repair: do NOT pass `currentOuter: undefined`
+        // when the user omits the flag. The service-layer branch
+        // `'currentOuter' in opts` returns true for an explicit
+        // `undefined` (the key exists on the spread object literal),
+        // which would skip the env-var fallback and pin `current =
+        // undefined` — always reading the presence as stale. Build a
+        // sparse opts object so the service can fall back to
+        // `getCurrentOuterSessionId()` (reads PEAKS_OUTER_SESSION_ID /
+        // CLAUDE_CODE_SESSION_ID).
+        const checkOpts = options.project !== undefined ? { projectRootOverride: options.project } : {};
+        if (options.currentOuter !== undefined) {
+            checkOpts.currentOuter = options.currentOuter;
+        }
+        const result = checkStalePresence(checkOpts);
+        // Always emit `currentOuterSessionId` in the JSON envelope (even
+        // when undefined → ''), per slice 002 AC-1 contract: downstream
+        // tooling (statusline, sub-agent dispatch) reads the field by
+        // name, never by `data.currentOuterSessionId ?? ''`. JSON.stringify
+        // drops `undefined` properties, so we coerce to '' before
+        // wrapping in the envelope.
+        const data = {
+            stale: result.stale,
+            reason: result.reason,
+            presence: result.presence,
+            currentOuterSessionId: result.currentOuterSessionId ?? '',
+            recordedOuterSessionId: result.recordedOuterSessionId ?? ''
+        };
+        printResult(io, ok('skill.presence:check-stale', data), options.json);
+    });
+    addJsonOption(skill
+        .command('heartbeat')
+        .description('Show the heartbeat status of the active Peaks skill')).action((options) => {
+        const presence = getSkillPresence();
+        if (presence === null) {
+            printResult(io, ok('skill.heartbeat', { active: false, heartbeat: 'none' }), options.json);
+            return;
+        }
+        printResult(io, ok('skill.heartbeat', {
+            active: true,
+            skill: presence.skill,
+            gate: presence.gate ?? null,
+            lastHeartbeat: presence.lastHeartbeat ?? presence.setAt,
+            setAt: presence.setAt
+        }), options.json);
+    });
+    addJsonOption(skill
+        .command('heartbeat:touch')
+        .description('Update the heartbeat timestamp (called by the LLM each turn to confirm peaks skill context is alive)')).action((options) => {
+        const updated = touchSkillHeartbeat();
+        if (updated === null) {
+            printResult(io, ok('skill.heartbeat:touch', { active: false, heartbeat: 'none' }), options.json);
+            return;
+        }
+        printResult(io, ok('skill.heartbeat:touch', {
+            active: true,
+            skill: updated.skill,
+            lastHeartbeat: updated.lastHeartbeat
+        }), options.json);
+    });
+    addJsonOption(skill
+        .command('detect-marker-loss')
+        .description('Detect whether the latest assistant message lost the Peaks-Loop status header while a peaks skill is still active (slice 028 detection primitive).')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--message <text>', 'latest assistant message text to scan (defaults to reading the most recent LLM response from the stdin pipe, or empty string when no pipe is attached)')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const message = options.message ?? '';
+        const result = detectPresenceMarker({ project: projectRoot, latestAssistantMessage: message });
+        printResult(io, ok('skill.detect-marker-loss', result), options.json);
+    });
+    // Slice S0 — register `peaks skill search`. Sibling subcommand to
+    // list / runbook / presence; preserves the existing surface
+    // (HC-10 — 老入口保留).
+    registerSkillSearchCommand(program, io);
+}

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

@@ -0,0 +1,351 @@
+/**
+ * `peaks sub-agent dispatch <role> ...` — slice 2026-06-07-sub-agent-context-governance.
+ *
+ * Pulled out of `sub-agent-commands.ts` (slice 2026-06-23-audit-p0-split) to
+ * honor the 800-line file cap (Karpathy #2 Simplicity First). The single
+ * `dispatch` action lives here; the `--from-dag` sibling was further split
+ * into `dispatch-from-dag.ts` (slice 2026-06-23-audit-3rd #7) because the
+ * two paths share no logic and the `--from-dag` codepath loads three heavy
+ * modules on first call (slice 9 perf) that the warm-path single-dispatch
+ * never touches.
+ *
+ * Skill-first / CLI-auxiliary red line (PB-4 / AC-19/20): this command is
+ * a primitive that the peaks-code / peaks-rd / peaks-qa SKILL.md compose.
+ * Users do NOT invoke it directly; the --help text and dispatch
+ * envelope's `nextActions` reinforce the point.
+ */
+import { existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { fail, getErrorMessage, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { detectInstalledIde } from '../../services/ide/ide-detector.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { SubAgentNotSupportedError } from '../../services/dispatch/sub-agent-dispatcher.js';
+import { emitObservabilityEvent, OBSERVABILITY_SUBAGENT_ROLES } from '../../services/observability/observability-service.js';
+import { noteDispatched, BATCH_LIMIT } from '../../services/dispatch/batch-counter.js';
+import { writeInitialDispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+import { evaluatePromptSize } from '../../services/context/context-guard.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { buildArtifactMeta, buildContextImpact } from '../../services/context/artifact-meta.js';
+import { assertSafeArtifactPath } from '../../services/context/dispatch-context-guard.js';
+import { compressPrompt } from '../../services/context/headroom-client.js';
+import { resolveHeadroomOptions } from '../../services/context/headroom-prefs.js';
+import { loadPreferences } from '../../services/preferences/preferences-service.js';
+import { DEFAULT_PREFERENCES } from '../../services/preferences/preferences-types.js';
+import { writeLogEntry } from '../../services/log/logger.js';
+import { HEADROOM_MODES, PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
+import { runDispatchFromDag } from './dispatch-from-dag.js';
+import { TEST_TOOL_DETECTION_BLOCK, formatTestToolDetection } from '../../services/dispatch/test-tool-detection.js';
+export function registerDispatchCommand(parent, io) {
+    addJsonOption(parent
+        .command('dispatch')
+        .description('Build an IDE-specific tool-call descriptor for a sub-agent dispatch. ' +
+        'Dry-run by design; the LLM executes the returned toolCall in its own ' +
+        'environment. Flags: --write-artifact (G7), --use-headroom (G7.7), ' +
+        '--force (G9 CLI 兜底). ' +
+        'See skills/peaks-code/references/sub-agent-dispatch.md for the ' +
+        'orchestrator contract.')
+        .argument('<role>', 'sub-agent role (e.g. rd | qa | ui | txt | qa-business | qa-business-api)')
+        // 2.7.0 slice-dag-dispatcher MVP: --prompt is required ONLY when --from-dag is NOT
+        // supplied. Previously this was `.requiredOption('--prompt')`, which blocked
+        // `dispatch --from-dag <file>` calls because commander.js validates
+        // `.requiredOption` before the action handler runs. The mutual-exclusion
+        // check is enforced below in the action body (--prompt XOR --from-dag).
+        .option('--prompt <text>', 'the prompt to send to the sub-agent (required unless --from-dag is provided)')
+        .option('--prompt-length <bytes>', 'DOGFOOD ONLY: synthesize a prompt of this size (overrides --prompt content for size only; content is "x" repeated)')
+        .option('--request-id <rid>', 'the same <rid> used by peaks request init')
+        .option('--session-id <sid>', 'override active session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--batch-id <uuid>', 'batch id for the dispatch (default: auto-generated UUID)')
+        .option('--write-artifact <path>', 'G7: register an artifact file at <path>; CLI computes sha256 + size + writes ArtifactMeta to the dispatch record')
+        .option('--use-headroom', 'G7.7/G9: compress the prompt via headroom-ai before dispatch (opt-in; falls back to G7 metadata-only if headroom unavailable)')
+        .option('--headroom-mode <mode>', `G7.7: headroom mode (${HEADROOM_MODES.join(' | ')}); default balanced`)
+        .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
+        .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')).action(async (role, options) => {
+        const asJson = options.json === true;
+        // 2.7.0 slice-dag-dispatcher MVP: --from-dag short-circuits the single
+        // sub-agent path and runs the full DAG plan via `dag-orchestrator`.
+        if (typeof options.fromDag === 'string' && options.fromDag.length > 0) {
+            await runDispatchFromDag(role, options, asJson, io);
+            return;
+        }
+        const validation = validateRole(role);
+        if (validation !== null) {
+            printResult(io, fail('sub-agent.dispatch', 'INVALID_ROLE', validation, { role, toolCall: null, dispatchRecordPath: null }, [
+                'Use a non-empty role string with no control characters.',
+                `Recommended: ${RECOMMENDED_ROLES}.`
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        if (!options.prompt || options.prompt.length === 0) {
+            printResult(io, fail('sub-agent.dispatch', 'MISSING_PROMPT', '--prompt is required when --from-dag is not provided', { role, toolCall: null, dispatchRecordPath: null }, [
+                'Re-run with either:',
+                '  • `--prompt <text>` for single-role dispatch, OR',
+                '  • `--from-dag <file>` for DAG-aware multi-slice dispatch (no --prompt needed; the per-slice prompt is generated from the DAG nodes).'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        // DOGFOOD ONLY: --prompt-length overrides the actual prompt content with
+        // a synthetic prompt of the given size in bytes. The original --prompt
+        // is still required (commander needs it). This avoids ARG_MAX limits
+        // on Windows when the dogfood prompt is > 200KB.
+        if (typeof options.promptLength === 'string' && options.promptLength.length > 0) {
+            const len = Number.parseInt(options.promptLength, 10);
+            if (Number.isInteger(len) && len > 0) {
+                options.prompt = 'x'.repeat(len);
+            }
+        }
+        if (options.prompt.length + TEST_TOOL_DETECTION_BLOCK.length > PROMPT_LIMIT_BYTES) {
+            printResult(io, fail('sub-agent.dispatch', 'PROMPT_TOO_LARGE', `prompt exceeds ${PROMPT_LIMIT_BYTES} bytes (got ${options.prompt.length})`, { role, toolCall: null, dispatchRecordPath: null }, [
+                'Truncate the prompt or split into multiple dispatches.',
+                'Pass --force to override the 80% threshold at CLI (NOT allowed at hook layer).'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        // G9 CLI 兜底 — evaluate prompt size against the threshold table.
+        const decision = evaluatePromptSize(options.prompt.length, { force: options.force === true });
+        if (!decision.allow) {
+            printResult(io, fail('sub-agent.dispatch', decision.code, `prompt size ${options.prompt.length} bytes exceeds threshold (tier=${decision.evaluation.tier}, ratio=${decision.evaluation.ratio.toFixed(3)})`, {
+                role,
+                toolCall: null,
+                dispatchRecordPath: null
+            }, [
+                decision.suggest ?? 'Trim prompt or pass --force to override at CLI.',
+                'PreToolUse hook layer will still reject regardless of --force (RL-30 strict).'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const projectRoot = options.project ?? process.cwd();
+            // Slice 2026-06-26-unknown-sid-fallback-fix: when --session-id is not
+            // passed, auto-resolve the active peaks session id from
+            // `.peaks/_runtime/session.json` (or PEAKS_SESSION_ID env var) so
+            // dispatch records land in `.peaks/_sub_agents/<real-sid>/` instead
+            // of the `unknown-sid` fallback. The unknown-sid branch is preserved
+            // as the last-resort so callers without a bound session (e.g. an
+            // ad-hoc dispatch in a fresh tree) still get a deterministic path.
+            const sid = options.sessionId
+                ?? process.env.PEAKS_SESSION_ID
+                ?? getCurrentSessionId(projectRoot)
+                ?? 'unknown-sid';
+            const rid = options.requestId ?? 'unknown-rid';
+            const batchId = options.batchId ?? randomUUID();
+            // G7.7 / G9: resolve headroom options from preferences + CLI overrides.
+            // Preferences hard-block when headroom.enabled=false (returns HEADROOM_DISABLED_BY_PREFERENCE).
+            // loadPreferences can throw on schema mismatch; we fall back to defaults to avoid
+            // breaking the dispatch on a stale preferences.json file.
+            let headroomPrefs = DEFAULT_PREFERENCES.headroom;
+            try {
+                headroomPrefs = loadPreferences(projectRoot).headroom;
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                // Keep default preferences; the user can re-run with explicit --headroom-mode
+                // if they want to override the fallback.
+            }
+            const headroomResolved = resolveHeadroomOptions(headroomPrefs, {
+                useHeadroom: options.useHeadroom === true,
+                ...(options.headroomMode !== undefined ? { headroomMode: options.headroomMode } : {})
+            });
+            if (headroomResolved.blocked !== null) {
+                printResult(io, fail('sub-agent.dispatch', headroomResolved.blocked, `headroom integration is disabled in preferences (headroom.enabled=false); pass --headroom-mode and update preferences first, or run without --use-headroom`, {
+                    role,
+                    toolCall: null,
+                    dispatchRecordPath: null
+                }, [
+                    'Edit .peaks/preferences.json: set headroom.enabled = true (per-touchpoint mode is headroom.perTouchpoint.subAgentDispatch).',
+                    'Or re-run without --use-headroom to dispatch without compression.'
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
+            const adapter = getAdapter(ide);
+            if (!adapter.subAgentDispatcher.supportsRole(role)) {
+                printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support role "${role}"`, { role, toolCall: null, dispatchRecordPath: null }, [
+                    'Switch to a registered IDE (e.g. claude-code) or pick a role the current IDE supports.'
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            // G7.7 headroom compress (opt-in). If headroom fails or is unavailable,
+            // fall back to the original prompt + emit warning.
+            let effectivePrompt = `${formatTestToolDetection()}\n\n${options.prompt}`;
+            let headroomCompressed = false;
+            let headroomResult = null;
+            const warnings = [...decision.warnings];
+            if (headroomResolved.mode !== null) {
+                headroomResult = await compressPrompt(effectivePrompt, headroomResolved.mode);
+                if (headroomResult.warning !== null) {
+                    warnings.push(headroomResult.warning);
+                }
+                if (headroomResult.compressed && headroomResult.compressedPrompt !== null) {
+                    effectivePrompt = headroomResult.compressedPrompt;
+                    headroomCompressed = true;
+                }
+            }
+            let toolCall;
+            try {
+                toolCall = adapter.subAgentDispatcher.buildToolCall({ role, prompt: effectivePrompt, requestId: rid, sessionId: sid });
+                // Slice C of v2.11.1 — observability hook #2/7. Fire-and-forget
+                // per PRD Q4 (full-auto must never fail-loud). The
+                // synchronous emit returns {written:false} on disk-full; we
+                // deliberately swallow the result so dispatch contract is
+                // unchanged. role is only included when it matches the schema's
+                // known sub-agent role set; otherwise it's omitted (non-standard
+                // roles like 'qa-business' would otherwise drop the event
+                // through schema rejection).
+                const KNOWN_ROLES = new Set(OBSERVABILITY_SUBAGENT_ROLES);
+                const knownRole = KNOWN_ROLES.has(role) ? role : null;
+                emitObservabilityEvent({
+                    schemaVersion: 1,
+                    ts: new Date().toISOString(),
+                    sessionId: sid,
+                    category: 'dispatch',
+                    ...(knownRole !== null ? { role: knownRole } : {}),
+                    detail: {
+                        requestId: rid,
+                        ide: adapter.subAgentDispatcher.label,
+                        promptBytes: effectivePrompt.length,
+                        headroomCompressed
+                    }
+                }, { projectRoot });
+            }
+            catch (error) {
+                if (error instanceof SubAgentNotSupportedError) {
+                    printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', error.message, { role, toolCall: null, dispatchRecordPath: null }, [
+                        'Switch IDE or pick a role the current IDE supports.'
+                    ]), asJson);
+                    process.exitCode = 1;
+                    return;
+                }
+                throw error;
+            }
+            // G7 — optional --write-artifact: build ArtifactMeta, attach to record.
+            let artifactMeta = null;
+            if (typeof options.writeArtifact === 'string' && options.writeArtifact.length > 0) {
+                try {
+                    assertSafeArtifactPath(options.writeArtifact, projectRoot);
+                    if (!existsSync(options.writeArtifact)) {
+                        warnings.push('ARTIFACT_NOT_FOUND');
+                    }
+                    else {
+                        artifactMeta = buildArtifactMeta({
+                            path: options.writeArtifact,
+                            rid,
+                            role,
+                            idx: 1, // single dispatch, idx=1
+                            summary: null
+                        });
+                    }
+                }
+                catch (err) {
+                    warnings.push(`ARTIFACT_PATH_INVALID: ${getErrorMessage(err)}`);
+                }
+            }
+            const { path: dispatchRecordPath } = writeInitialDispatchRecord({
+                projectRoot,
+                sessionId: sid,
+                requestId: rid,
+                role,
+                prompt: effectivePrompt,
+                toolCall,
+                batchId
+            });
+            const counter = noteDispatched(projectRoot, sid, batchId);
+            if (counter.warning) {
+                warnings.push(counter.warning.message);
+            }
+            const contextImpact = buildContextImpact({
+                promptSize: effectivePrompt.length,
+                artifactSizes: artifactMeta ? [artifactMeta.size] : []
+            });
+            const nextActions = [
+                'Tool call is dry-run; LLM must execute the tool to actually dispatch the sub-agent.',
+                'After dispatching, the sub-agent should call `peaks sub-agent heartbeat --record ' + dispatchRecordPath + '` periodically.'
+            ];
+            if (counter.warning) {
+                nextActions.push(`Batch is over the RL-1 limit (${BATCH_LIMIT}); consider splitting into multiple batches.`);
+            }
+            if (headroomResult && headroomResult.warning === 'HEADROOM_UNAVAILABLE') {
+                nextActions.push('Headroom daemon unavailable; dispatched with G7 metadata-only fallback.');
+            }
+            printResult(io, ok('sub-agent.dispatch', {
+                // Slice 2026-06-23-audit-4th #E1: every CLI envelope carries
+                // an envelopeVersion marker so consumers can detect contract
+                // changes (the previous #4 dropped `data.prompt` silently).
+                envelopeVersion: '2.2.0',
+                role,
+                ide: adapter.subAgentDispatcher.label,
+                // Slice 2026-06-23-audit-3rd #4: do NOT echo `prompt` in stdout.
+                // Prompts can carry user content (sometimes test credentials /
+                // internal URLs) that has no business landing in shell history,
+                // log aggregators, or tmux scrollback. The dispatch record on
+                // disk (gitignored under .peaks/_sub_agents/) keeps the prompt
+                // for the sub-agent to read; CLI stdout stays metadata-only.
+                // Surface promptSize + originalPromptSize so the LLM-side
+                // runner can still reason about headroom without seeing the
+                // content.
+                originalPromptSize: options.prompt.length,
+                promptSize: effectivePrompt.length,
+                toolCall,
+                dispatchRecordPath,
+                batchId,
+                dispatchedInBatch: counter.count,
+                headroomCompressed,
+                headroomResult: headroomResult
+                    ? {
+                        mode: headroomResult.mode,
+                        compressed: headroomResult.compressed,
+                        compressionRatio: headroomResult.compressionRatio,
+                        tokensSaved: headroomResult.tokensSaved,
+                        warning: headroomResult.warning
+                    }
+                    : null,
+                forcedAt: decision.forcedAt,
+                contextImpact,
+                artifactMetas: artifactMeta ? [artifactMeta] : []
+            }, warnings, nextActions), asJson);
+            // Slice 2026-06-23-audit-4th #B1: structured log on success path.
+            // Best-effort: writeLogEntry swallows its own errors (logger.ts:155-159),
+            // so a full disk or missing ~/.peaks/logs/ dir never blocks the dispatch.
+            try {
+                writeLogEntry({
+                    ts: new Date().toISOString(),
+                    level: 'info',
+                    command: 'sub-agent.dispatch',
+                    msg: 'dispatched',
+                    sessionId: sid,
+                    batchId,
+                    data: {
+                        rid,
+                        role,
+                        batchId,
+                        dispatchedInBatch: counter.count,
+                        headroomCompressed,
+                        forcedAt: decision.forcedAt
+                    }
+                });
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                /* best-effort */
+            }
+        }
+        catch (error) {
+            printResult(io, fail('sub-agent.dispatch', 'DISPATCH_ERROR', getErrorMessage(error), { role, toolCall: null, dispatchRecordPath: null }, [
+                'See error message; if you are dispatching from a SKILL.md, the LLM should retry with a smaller prompt or pick a different role.'
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+}
+/**
+ * 2.7.0 slice-dag-dispatcher MVP — see `dispatch-from-dag.ts`.
+ * The function was pulled out of this file in slice 2026-06-23-audit-3rd
+ * #7 to honor the 800-line file cap and isolate the three heavy
+ * module loads (slice-dag / dag-orchestrator / contract-store) to the
+ * --from-dag codepath only.
+ */