peaks-loop 4.0.17 → 4.0.18

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 4.0.18 — 2026-08-10 (statusline 24h overlay)
+
+**Bug fix — statusline doesn't reflect 24h mode substate after transition**:
+- `src/services/skills/skill-statusline-service.ts`: adds `read24hOverlay` helper (name-distinct from canonical `src/services/24h-mode/store.ts:108 read24hState` so the two readers with divergent null vs empty-snapshot semantics are not confused); adds `TwentyFourHourOverlay` type (minimal `{ state: string }`); adds `twentyFourHourState: TwentyFourHourOverlay | null` field to `StatusLineModel`; populates the field in all 5 return paths of `buildStatusLineModel` (lines for projectRoot-null, invalid-presence, idle, outer-mismatch idle, and final active/stale — only the active branch calls `read24hOverlay`).
+- `src/services/skills/skill-statusline-renderer.ts`: adds `format24hSuffix(overlay, palette, capability, noColor)` exported helper; extends `renderActive` signature to a 7th arg `twentyFourHourState`; appends `[24h-<state.toLowerCase()>]` suffix in 3 active-return branches (attention-gate / activeLeaf / normal); updates the call site at line 822.
+- 12 new vitest cases in `tests/unit/skills/skill-statusline-sid-only-marker.test.ts` (3 service-layer `read24hOverlay` + 1 `buildStatusLineModel` integration + 3 `format24hSuffix` helper-level + 4 renderer-integration AC-1..AC-4 + 1 malformed-shape hardening).
+- 5 typed-fixture sites updated to include `twentyFourHourState: null` (`tests/unit/services/skills/skill-statusline-renderer.test.ts` 5 factories + `tests/unit/skills/skill-statusline-sid-only-marker.test.ts` 3 directly-constructed literals).
+
+**Safety semantics preserved**:
+- v2.15.0 `presence:check-stale --project . --json` still returns `stale: true` on outer-mismatch. `skill-presence-service.ts` / `presence-lease-service.ts` / `workspace-service.ts` / `session/**` / `audit/**` / `src/services/24h-mode/**` / `src/cli/commands/session-24h-mode.ts` are FORBIDDEN files in this slice — zero edits.
+- No new dependencies. No enum/API/command-surface changes.
+
+**Migration**: zero changes required for existing users. Active 24h mode sessions automatically pick up the new `[24h-<state>]` suffix on next statusline render after the user runs `peaks session 24h-mode transition`. Sessions without a 24h-state.json file render unchanged (back-compat).
+
 ## 4.0.17 — 2026-08-07 (Vitest worker cap + statusline SIGTERM + 9-slice shipped)
 
 **Core fix — vitest worker concurrency cap (root-cause)**:

package/dist/cli/commands/primer-command.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Slice rid-statusline-stale-ux AC-2: `peaks session primer --project <path>`.
+ *
+ * Lightweight SessionStart primer that fires rotation + presence
+ * cleanup BEFORE the first statusline render of a fresh session.
+ * Independent subcommand (NOT a flag on `peaks workspace init` per
+ * task regulation: "don't add a flag to workspace init"). Cleaner
+ * permission boundary — primer cannot be mistaken for init by users.
+ *
+ * Performs only 3 things:
+ *   1. ensureSessionWithRotation(projectRoot) — the real rotation
+ *      entry point (verified at
+ *      src/services/session/session-binding-bridge.ts:461-527).
+ *   2. If outer-mismatch rotation occurred: call
+ *      clearStalePresenceOnRotation with the verified single-options-
+ *      object signature (mirrors init-command.ts:324-329 pattern with
+ *      all 3 fields populated). Note: on 4.0.11-A sid-scoped leases
+ *      this is a legacy-compat no-op; the real cleanup mechanism is
+ *      rotation itself (rebinding changes the bound sid so the
+ *      reader looks in the new sid's empty lease dir).
+ *   3. gcStalePresenceLeases({ projectRoot, trigger: 'manual' }) —
+ *      sync; documented as legacy-compat no-op on 4.0.11-A sid-scoped
+ *      data.
+ *
+ * SKIPS (per RD §4.2.1):
+ *   - bootstrapProjectScan
+ *   - materializeClaudeSettingsLocal
+ *   - resolveFirstTimeHooksInstall
+ *   - applyHookInstall (prevents accidental first-launch hook install)
+ *
+ * Mounted as a CHILD of the existing `session` commander group at
+ * `src/cli/commands/core/session-command.ts:32` (verified pattern:
+ * `session.command('list')...`). NOT `program.command('session primer')`.
+ *
+ * The action handler is exported as `runPrimerAction` so the
+ * integration test suite can drive it directly without going through
+ * Commander's argv-parsing wrapper (which would mangle empty /
+ * whitespace / NUL-byte inputs before reaching the action body).
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export type PrimerOptions = {
+    project: string;
+    json?: boolean;
+};
+/**
+ * Pure action body for `peaks session primer`. Exported so
+ * integration tests can drive it directly with crafted inputs (empty
+ * string, whitespace, NUL byte) that would otherwise be rejected by
+ * Commander's argv parser.
+ *
+ * Returns `{ exitCode: 0 | 1 }` so callers (CLI path or test path)
+ * can apply the exit code uniformly. NEVER calls `process.exit` —
+ * exits are the responsibility of the CLI wrapper.
+ */
+export declare function runPrimerAction(opts: PrimerOptions, io: ProgramIO): Promise<{
+    exitCode: 0 | 1;
+}>;
+export declare function registerPrimerCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/primer-command.js

@@ -0,0 +1,160 @@
+/**
+ * Slice rid-statusline-stale-ux AC-2: `peaks session primer --project <path>`.
+ *
+ * Lightweight SessionStart primer that fires rotation + presence
+ * cleanup BEFORE the first statusline render of a fresh session.
+ * Independent subcommand (NOT a flag on `peaks workspace init` per
+ * task regulation: "don't add a flag to workspace init"). Cleaner
+ * permission boundary — primer cannot be mistaken for init by users.
+ *
+ * Performs only 3 things:
+ *   1. ensureSessionWithRotation(projectRoot) — the real rotation
+ *      entry point (verified at
+ *      src/services/session/session-binding-bridge.ts:461-527).
+ *   2. If outer-mismatch rotation occurred: call
+ *      clearStalePresenceOnRotation with the verified single-options-
+ *      object signature (mirrors init-command.ts:324-329 pattern with
+ *      all 3 fields populated). Note: on 4.0.11-A sid-scoped leases
+ *      this is a legacy-compat no-op; the real cleanup mechanism is
+ *      rotation itself (rebinding changes the bound sid so the
+ *      reader looks in the new sid's empty lease dir).
+ *   3. gcStalePresenceLeases({ projectRoot, trigger: 'manual' }) —
+ *      sync; documented as legacy-compat no-op on 4.0.11-A sid-scoped
+ *      data.
+ *
+ * SKIPS (per RD §4.2.1):
+ *   - bootstrapProjectScan
+ *   - materializeClaudeSettingsLocal
+ *   - resolveFirstTimeHooksInstall
+ *   - applyHookInstall (prevents accidental first-launch hook install)
+ *
+ * Mounted as a CHILD of the existing `session` commander group at
+ * `src/cli/commands/core/session-command.ts:32` (verified pattern:
+ * `session.command('list')...`). NOT `program.command('session primer')`.
+ *
+ * The action handler is exported as `runPrimerAction` so the
+ * integration test suite can drive it directly without going through
+ * Commander's argv-parsing wrapper (which would mangle empty /
+ * whitespace / NUL-byte inputs before reaching the action body).
+ */
+import { printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRootStrict, InvalidProjectRootError } from '../../services/config/config-safety.js';
+import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
+import { clearStalePresenceOnRotation } from '../../services/skills/skill-presence-service.js';
+import { gcStalePresenceLeases } from '../../services/skills/presence-lease-service.js';
+/**
+ * Pure action body for `peaks session primer`. Exported so
+ * integration tests can drive it directly with crafted inputs (empty
+ * string, whitespace, NUL byte) that would otherwise be rejected by
+ * Commander's argv parser.
+ *
+ * Returns `{ exitCode: 0 | 1 }` so callers (CLI path or test path)
+ * can apply the exit code uniformly. NEVER calls `process.exit` —
+ * exits are the responsibility of the CLI wrapper.
+ */
+export async function runPrimerAction(opts, io) {
+    // Explicit empty / whitespace-only guard BEFORE the strict
+    // resolver. Commander's requiredOption checks presence, not
+    // emptiness; node's `resolve('')` returns cwd (silent
+    // fall-through), so we must short-circuit explicitly.
+    if (!opts.project || opts.project.trim() === '') {
+        printResult(io, fail('session.primer', 'PRIMER_EMPTY_PROJECT', '--project <path> required and must be non-empty', { project: opts.project }, ['Pass a non-empty absolute path to --project']), opts.json);
+        return { exitCode: 1 };
+    }
+    // P1 H1 option A: use NEW strict helper. Throws on NUL /
+    // non-canonical / non-existent path. The fail-open
+    // `resolveCanonicalProjectRoot` is not safe here because primer
+    // is invoked from a SessionStart hook on a path pulled from
+    // `${CLAUDE_PROJECT_DIR}` — the env var is user-controlled and
+    // may contain path traversal payloads.
+    let projectRoot;
+    try {
+        projectRoot = resolveCanonicalProjectRootStrict(opts.project);
+    }
+    catch (error) {
+        if (error instanceof InvalidProjectRootError) {
+            printResult(io, fail('session.primer', `PRIMER_INVALID_PROJECT_ROOT_${error.reason.replace(/-/g, '_').toUpperCase()}`, error.message, { project: opts.project, reason: error.reason }, ['Pass a non-empty absolute canonical path to --project']), opts.json);
+            return { exitCode: 1 };
+        }
+        throw error;
+    }
+    // Real rotation entry point (verified
+    // src/services/session/session-binding-bridge.ts:461-527).
+    // NOT the invented `runRotationCheck` from cycle-2 RD.
+    const rotation = await ensureSessionWithRotation(projectRoot);
+    const rotationOccurred = rotation.previousSessionId !== null
+        && rotation.rotationReason === 'outer-session-mismatch';
+    let clearOutcome = null;
+    if (rotationOccurred) {
+        // VERIFIED single-options-object signature (see
+        // skill-presence-service.ts:584-588). Mirror the real caller
+        // pattern at init-command.ts:324-329 with all 3 fields
+        // populated. NOTE: on 4.0.11-A sid-scoped leases this is a
+        // legacy-compat no-op (clearSkillPresence only unlinks legacy
+        // single-slot files; the real cleanup mechanism is rotation
+        // itself).
+        clearOutcome = clearStalePresenceOnRotation({
+            projectRootOverride: projectRoot,
+            currentOuterSessionId: process.env.PEAKS_OUTER_SESSION_ID
+                ?? process.env.CLAUDE_CODE_SESSION_ID,
+            rotatedOutSessionId: rotation.previousSessionId
+        });
+    }
+    // Sync call (verified presence-lease-service.ts:383-414) —
+    // documented as legacy-compat no-op on 4.0.11-A sid-scoped
+    // data; iterates `input.leases ?? []` and gets `[]` on the
+    // real init-command.ts:463-466 caller.
+    const gcOutcome = gcStalePresenceLeases({
+        projectRoot,
+        trigger: 'manual'
+    });
+    printResult(io, ok('session.primer', {
+        projectRoot,
+        sessionId: rotation.sessionId,
+        rotationOccurred,
+        ...(rotation.previousSessionId !== null
+            ? { previousSessionId: rotation.previousSessionId }
+            : {}),
+        clearOutcome,
+        gcOutcome: {
+            removed: gcOutcome.removed,
+            retained: gcOutcome.retained
+        }
+    }), opts.json);
+    return { exitCode: 0 };
+}
+export function registerPrimerCommand(program, io) {
+    // Reuse the existing `session` commander group registered earlier
+    // in `createProgram` (via autoRegisterAllCommands → session-command.ts:32).
+    // Creating a new `program.command('session')` here throws
+    // `cannot add command 'session' as already have command 'session'`
+    // because commander disallows duplicate top-level command names.
+    // This regression was caught in publish.yml gate-changeset step
+    // (run #134, exit 1) on the first 4.0.18 release attempt.
+    const session = program.commands.find((c) => c.name() === 'session');
+    if (!session) {
+        throw new Error('registerPrimerCommand: session group not registered; ' +
+            'autoRegisterAllCommands must run before registerPrimerCommand');
+    }
+    session
+        .command('primer')
+        .description('Lightweight SessionStart primer: rotation + presence cleanup. ' +
+        'Does NOT bootstrap project scan / materialize settings / install hooks. ' +
+        'Idempotent; safe to run on every SessionStart.')
+        .requiredOption('--project <path>', 'Project root (must be non-empty canonical path)')
+        .option('--json', 'emit a JSON envelope { ok, data } to stdout')
+        .action(async (opts) => {
+        try {
+            const { exitCode } = await runPrimerAction(opts, io);
+            if (exitCode !== 0) {
+                process.exitCode = exitCode;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            printResult(io, fail('session.primer', 'PRIMER_FAILED', message, { project: opts.project }, ['Verify the project path exists, is writable, and is canonical']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/program.js

@@ -16,6 +16,7 @@ import { registerCronSchedulerCommand } from './commands/cron-scheduler-commands
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
 import { registerSopCommands } from './commands/sop-commands.js';
 import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
+import { registerPrimerCommand } from './commands/primer-command.js';
 import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 import { printSuperCommandCatalog } from './cli-helpers.js';
@@ -209,5 +210,12 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // registerCoreAndArtifactCommands instead of being created twice.
     autoRegisterAllCommands(program, io);
     registerSkillVisibilityCommand(program, repoRoot);
+    // Slice rid-statusline-stale-ux AC-2: register `peaks session primer`
+    // so it appears in `peaks session --help` for LLM `<TAB>`-discovery.
+    // Mounted as a CHILD of the existing `session` commander group
+    // (verified at src/cli/commands/core/session-command.ts:32). NOT
+    // `program.command('session primer')` (that registers a single
+    // literal command name, not a child of the session group).
+    registerPrimerCommand(program, io);
     return program;
 }

package/dist/services/config/config-safety.d.ts

@@ -28,6 +28,29 @@ export declare function resolveProjectRootForConfig(startPath: string): string;
  * `git rev-parse` exit; both fall through to the heuristic.
  */
 export declare function resolveCanonicalProjectRoot(startPath: string): string;
+/**
+ * Slice rid-statusline-stale-ux AC-2 + P1 H1 option A: strict
+ * canonicalization for use in trust-boundary paths (e.g.
+ * `peaks session primer`).
+ *
+ * Unlike `resolveCanonicalProjectRoot` (fail-open, returns `start`
+ * on any resolution failure), this helper THROWS on:
+ *   - empty / whitespace-only input
+ *   - NUL byte in input
+ *   - non-existent path (realpathSync ENOENT)
+ *   - non-canonical (symlink) input (when the input path and its
+ *     realpath differ in a way that suggests the user passed a
+ *     symlinked path through a security-sensitive surface)
+ *
+ * Existing fail-open `resolveCanonicalProjectRoot` is retained for
+ * back-compat — many callers depend on the fail-open behavior
+ * (e.g. `init-command.ts:32`). The strict variant is opt-in.
+ */
+export declare class InvalidProjectRootError extends Error {
+    readonly reason: 'empty' | 'nul-byte' | 'non-existent' | 'non-canonical';
+    constructor(reason: 'empty' | 'nul-byte' | 'non-existent' | 'non-canonical', input: string);
+}
+export declare function resolveCanonicalProjectRootStrict(startPath: string): string;
 export declare function getProjectConfigPath(projectRoot: string | null): string | null;
 export declare function getProjectBootstrapConfigPath(projectRoot: string): string;
 export declare function validateProjectBootstrapConfigPathForWrite(projectRoot: string, configPath: string): void;

package/dist/services/config/config-safety.js

@@ -131,6 +131,68 @@ export function resolveCanonicalProjectRoot(startPath) {
     }
     return start;
 }
+/**
+ * Slice rid-statusline-stale-ux AC-2 + P1 H1 option A: strict
+ * canonicalization for use in trust-boundary paths (e.g.
+ * `peaks session primer`).
+ *
+ * Unlike `resolveCanonicalProjectRoot` (fail-open, returns `start`
+ * on any resolution failure), this helper THROWS on:
+ *   - empty / whitespace-only input
+ *   - NUL byte in input
+ *   - non-existent path (realpathSync ENOENT)
+ *   - non-canonical (symlink) input (when the input path and its
+ *     realpath differ in a way that suggests the user passed a
+ *     symlinked path through a security-sensitive surface)
+ *
+ * Existing fail-open `resolveCanonicalProjectRoot` is retained for
+ * back-compat — many callers depend on the fail-open behavior
+ * (e.g. `init-command.ts:32`). The strict variant is opt-in.
+ */
+export class InvalidProjectRootError extends Error {
+    reason;
+    constructor(reason, input) {
+        super(`Invalid project root (${reason}): "${input}"`);
+        this.reason = reason;
+        this.name = 'InvalidProjectRootError';
+    }
+}
+export function resolveCanonicalProjectRootStrict(startPath) {
+    if (!startPath || startPath.trim() === '') {
+        throw new InvalidProjectRootError('empty', startPath);
+    }
+    if (startPath.indexOf('\0') !== -1) {
+        throw new InvalidProjectRootError('nul-byte', startPath);
+    }
+    const start = resolve(startPath);
+    let realStart;
+    try {
+        realStart = realpathSync(start);
+    }
+    catch {
+        throw new InvalidProjectRootError('non-existent', startPath);
+    }
+    if (realStart !== start) {
+        // User passed a path through a symlink; reject as non-canonical
+        // for trust-boundary entry points.
+        throw new InvalidProjectRootError('non-canonical', startPath);
+    }
+    // Delegate to the existing canonicalization (git root → heuristic)
+    // AFTER the strict pre-checks pass.
+    const canonical = resolveCanonicalProjectRoot(startPath);
+    if (canonical === startPath || canonical === realStart) {
+        return canonical;
+    }
+    // Canonicalization moved the path (e.g. to a git root) — accept it
+    // but ensure it also exists.
+    try {
+        realpathSync(canonical);
+        return canonical;
+    }
+    catch {
+        throw new InvalidProjectRootError('non-existent', startPath);
+    }
+}
 function resolveProjectRootFromGit(startPath) {
     // execFileSync (not execSync) so a malicious `startPath` cannot
     // inject argv into the spawned git invocation. The child only

package/dist/services/skills/hooks-settings-service.js

@@ -4,7 +4,7 @@ import { resolve } from 'node:path';
 import { assertSafeSettingsFile } from '../ide/shared/safe-path.js';
 import { atomicWriteJson, readJsonObjectFile } from '../ide/shared/atomic-json.js';
 import { getAdapter } from '../ide/ide-registry.js';
-import { HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL } from './outer-cache-hook-constants.js';
+import { HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL, HOOK_WORKSPACE_INIT_COMMAND, HOOK_WORKSPACE_INIT_EVENT, HOOK_WORKSPACE_INIT_SENTINEL } from './session-start-hook-constants.js';
 // --- Module-level defaults (claude-code) -----------------------------------
 // These exports remain for backward compat — tests and downstream callers
 // that only care about Claude Code can keep importing them. The per-IDE
@@ -211,6 +211,20 @@ function resolveHookEntries(ide, _skipProgress = false) {
             command: HOOK_OUTER_CACHE_COMMAND,
             event: HOOK_OUTER_CACHE_EVENT
         });
+        // Slice rid-statusline-stale-ux AC-2: SessionStart outer-cache
+        // write is followed by `peaks session primer` entry so that
+        // rotation + presence cleanup fire BEFORE the first statusline
+        // render of a fresh session. The new subcommand is idempotent
+        // and short-circuits when the binding already matches — safe to
+        // call on every SessionStart. Order matters conceptually:
+        // outer-cache write must come first (the primer's
+        // ensureSessionWithRotation reads the current outer session id).
+        entries.push({
+            sentinel: HOOK_WORKSPACE_INIT_SENTINEL,
+            matcher: '',
+            command: HOOK_WORKSPACE_INIT_COMMAND,
+            event: HOOK_WORKSPACE_INIT_EVENT
+        });
         // Slice 2026-08-06-codegate-vendor-neutral: code-gate entry on
         // Edit|Write|MultiEdit matcher. Vendor-neutral command
         // (`peaks code-gate --json`); the CLI adapter lives in
@@ -242,7 +256,12 @@ function resolveLegacySentinels(ide) {
     // the rest of the peaks-managed entries.
     const base = [HOOK_ENFORCE_SENTINEL, LEGACY_PROGRESS_START_SENTINEL, HOOK_CODE_GATE_SENTINEL];
     if (ide === 'claude-code') {
-        return [...base, HOOK_OUTER_CACHE_SENTINEL];
+        // Slice rid-statusline-stale-ux AC-2: include the SessionStart
+        // workspace-init primer sentinel so uninstall strips it alongside
+        // the gate-enforce entry, and so hand-added entries matching this
+        // sentinel are recognized as peaks-managed (not stripped as
+        // non-Peaks).
+        return [...base, HOOK_OUTER_CACHE_SENTINEL, HOOK_WORKSPACE_INIT_SENTINEL];
     }
     return base;
 }

package/dist/services/skills/{outer-cache-hook-constants.d.ts → session-start-hook-constants.d.ts}

@@ -15,6 +15,13 @@
  * Only Claude Code supports SessionStart today; future adapters opt
  * in by extending `resolveHookEntries` and adding an adapter-driven
  * substitution for the `${...}` project-dir placeholder.
+ *
+ * Slice rid-statusline-stale-ux AC-2: renamed from
+ * `outer-cache-hook-constants.ts` (per RD §10 M-3) and extended with
+ * the SessionStart workspace-init primer constants. The primer fires
+ * `peaks session primer --project <path>` immediately after the
+ * outer-cache write so rotation + presence cleanup run BEFORE the
+ * first statusline render of a fresh session.
  */
 /** Sentinel substring identifying a SessionStart outer-cache hook entry. */
 export declare const HOOK_OUTER_CACHE_SENTINEL = "peaks outer-cache write";
@@ -22,3 +29,16 @@ export declare const HOOK_OUTER_CACHE_SENTINEL = "peaks outer-cache write";
 export declare const HOOK_OUTER_CACHE_COMMAND = "peaks outer-cache write --project \"${CLAUDE_PROJECT_DIR}\"";
 /** SessionStart hook event key for Claude Code. */
 export declare const HOOK_OUTER_CACHE_EVENT = "SessionStart";
+/**
+ * Slice rid-statusline-stale-ux AC-2: SessionStart workspace-init
+ * primer sentinel. Identifies the SessionStart entry that runs
+ * `peaks session primer --project <path>` so rotation + presence
+ * cleanup fire on every fresh session, before the first statusline
+ * render of that session. The primer is idempotent and short-
+ * circuits when the binding already matches.
+ */
+export declare const HOOK_WORKSPACE_INIT_SENTINEL = "peaks session primer";
+/** SessionStart hook command for the primer. */
+export declare const HOOK_WORKSPACE_INIT_COMMAND = "peaks session primer --project \"${CLAUDE_PROJECT_DIR}\"";
+/** SessionStart hook event key (same as outer-cache). */
+export declare const HOOK_WORKSPACE_INIT_EVENT = "SessionStart";

package/dist/services/skills/{outer-cache-hook-constants.js → session-start-hook-constants.js}

@@ -15,6 +15,13 @@
  * Only Claude Code supports SessionStart today; future adapters opt
  * in by extending `resolveHookEntries` and adding an adapter-driven
  * substitution for the `${...}` project-dir placeholder.
+ *
+ * Slice rid-statusline-stale-ux AC-2: renamed from
+ * `outer-cache-hook-constants.ts` (per RD §10 M-3) and extended with
+ * the SessionStart workspace-init primer constants. The primer fires
+ * `peaks session primer --project <path>` immediately after the
+ * outer-cache write so rotation + presence cleanup run BEFORE the
+ * first statusline render of a fresh session.
  */
 /** Sentinel substring identifying a SessionStart outer-cache hook entry. */
 export const HOOK_OUTER_CACHE_SENTINEL = 'peaks outer-cache write';
@@ -22,3 +29,16 @@ export const HOOK_OUTER_CACHE_SENTINEL = 'peaks outer-cache write';
 export const HOOK_OUTER_CACHE_COMMAND = `peaks outer-cache write --project "\${CLAUDE_PROJECT_DIR}"`;
 /** SessionStart hook event key for Claude Code. */
 export const HOOK_OUTER_CACHE_EVENT = 'SessionStart';
+/**
+ * Slice rid-statusline-stale-ux AC-2: SessionStart workspace-init
+ * primer sentinel. Identifies the SessionStart entry that runs
+ * `peaks session primer --project <path>` so rotation + presence
+ * cleanup fire on every fresh session, before the first statusline
+ * render of that session. The primer is idempotent and short-
+ * circuits when the binding already matches.
+ */
+export const HOOK_WORKSPACE_INIT_SENTINEL = 'peaks session primer';
+/** SessionStart hook command for the primer. */
+export const HOOK_WORKSPACE_INIT_COMMAND = `peaks session primer --project "\${CLAUDE_PROJECT_DIR}"`;
+/** SessionStart hook event key (same as outer-cache). */
+export const HOOK_WORKSPACE_INIT_EVENT = 'SessionStart';

package/dist/services/skills/skill-statusline-renderer.d.ts

@@ -1,4 +1,4 @@
-import type { StatusLineModel } from './skill-statusline-service.js';
+import type { StatusLineModel, TwentyFourHourOverlay } from './skill-statusline-service.js';
 import { computeRootSuffix as computeRootSuffixImpl } from './skill-statusline-sid-suffix.js';
 export { formatShortSid } from './skill-statusline-sid-suffix.js';
 export declare const computeRootSuffix: typeof computeRootSuffixImpl;
@@ -17,6 +17,55 @@ export type StatusLineCapability = 'ansi-unicode' | 'unicode' | 'ascii';
 export interface StatusLineRenderOptions {
     readonly capability: StatusLineCapability;
 }
+/**
+ * Glyph palette per capability. Status glyphs (active / idle / warning),
+ * separators (· / › / ▸ / ASCII variants), and the diagnostic marker
+ * (`presence unreadable`). Unicode glyphs use widely-supported characters;
+ * ASCII keeps byte-identical shape across encodings.
+ *
+ * Compact glyphs are the unicode quadrant marks ◐◑◒◓, the check ✓, and the
+ * ballot ✕. ASCII uses bracket/plus/star/x. Bar characters are █/░ in
+ * unicode and #/- in ASCII. Ratios are joined with `·` (` . ` for ASCII)
+ * and the before→after arrow is `→` (-> for ASCII).
+ */
+interface StatusPalette {
+    readonly active: string;
+    readonly idleStale: string;
+    readonly idle: string;
+    readonly warning: string;
+    readonly inlineSeparator: string;
+    readonly trailSeparator: string;
+    readonly idleLabel: string;
+    readonly invalidMessage: string;
+    readonly compact: CompactPalette;
+    readonly barFilled: string;
+    readonly barEmpty: string;
+    readonly ratioArrow: string;
+}
+interface CompactPalette {
+    readonly queued: string;
+    readonly preparing: string;
+    readonly compacting: string;
+    readonly verifying: string;
+    readonly completed: string;
+    readonly failed: string;
+}
+export declare function formatHumanAge(ageMs: number | null): string;
+/**
+ * Slice rid-statusline-24h-overlay (2026-08-10): format the 24h-mode
+ * overlay suffix appended after the existing `<baseMode>` token in
+ * the ACTIVE state. Returns `''` when the overlay is `null` (missing
+ * file / corrupt file / wrong shape — see `read24hOverlay`).
+ *
+ * Output shape (ASCII palette): ` . [24h-<lowercase-state>]`
+ * Output shape (unicode palette): ` · [24h-<lowercase-state>]`
+ *
+ * en-US only; i18n deferred to a future slice (PRD §Non-goals.5).
+ * The `[24h-...]` prefix is a deliberate marker so the user can
+ * visually distinguish a 24h-mode substate from a base-mode token
+ * like `[full-auto]`.
+ */
+export declare function format24hSuffix(overlay: TwentyFourHourOverlay | null, palette: StatusPalette, capability: StatusLineCapability, noColor: boolean): string;
 export declare function resolveStatusLineCapability(input: {
     readonly env: NodeJS.ProcessEnv;
     readonly isTTY: boolean;

package/dist/services/skills/skill-statusline-renderer.js

@@ -108,6 +108,12 @@ function buildPalette(capability, noColor) {
         return {
             active: '*',
             idle: 'o',
+            // Slice rid-statusline-stale-ux AC-1: stale residue uses the same
+            // glyph as `idle` (`o`) but stays static (no slow-blink — the user
+            // is reading a *previous* session's residue, not a live idle state).
+            // The neutral copy `(previous session · N days ago)` is the
+            // decisive signal; the glyph is auxiliary.
+            idleStale: 'o',
             warning,
             inlineSeparator: ' . ',
             trailSeparator: ' -> ',
@@ -125,6 +131,11 @@ function buildPalette(capability, noColor) {
     return {
         active: brandGlyph('●'),
         idle: blinkBrand('○'),
+        // Slice rid-statusline-stale-ux AC-1: muted slate (`#AAAAC8` dim)
+        // — slow-blink OFF, distinct from `idle` (slow-blink brand) and
+        // `warning` (yellow invalid-presence). The stale branch is
+        // semantically "previous-session residue" (neutral), NOT an error.
+        idleStale: dimBrand('○'),
         warning,
         inlineSeparator: brand(' · '),
         trailSeparator: brand(' → '),
@@ -181,6 +192,10 @@ function paletteFor(capability, noColor) {
     return buildPalette(capability ?? DEFAULT_CAPABILITY, noColor);
 }
 function formatAge(ageMs) {
+    // Slice rid-statusline-stale-ux AC-1: this legacy `stale <N>h/m`
+    // token is NO LONGER used by renderStale. Kept exported / defined
+    // for any downstream caller / test that still asserts against the
+    // `stale` substring. The active renderer path uses `formatHumanAge`.
     if (ageMs === null)
         return '';
     const hours = Math.round(ageMs / (60 * 60 * 1000));
@@ -189,11 +204,69 @@ function formatAge(ageMs) {
     const minutes = Math.max(1, Math.round(ageMs / (60 * 1000)));
     return `stale ${minutes}m`;
 }
+// Slice rid-statusline-stale-ux AC-1 + perf H2: human-friendly neutral
+// age label for the stale branch. en-US strings per RD §5 R1 (codebase
+// consistency); zh-CN deferred to a future i18n slice. Backed by a
+// bounded Map cache (parity with `formatShortSid` memoization at
+// `skill-statusline-sid-suffix.ts`).
+const HUMAN_AGE_CACHE = new Map();
+const HUMAN_AGE_CACHE_LIMIT = 16;
+export function formatHumanAge(ageMs) {
+    if (ageMs === null)
+        return 'unknown';
+    const cached = HUMAN_AGE_CACHE.get(ageMs);
+    if (cached !== undefined)
+        return cached;
+    let result;
+    if (ageMs < 5 * 60 * 1000) {
+        result = 'just now';
+    }
+    else {
+        const minutes = Math.round(ageMs / (60 * 1000));
+        if (minutes < 60) {
+            result = `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+        }
+        else {
+            const hours = Math.round(ageMs / (60 * 60 * 1000));
+            if (hours < 24) {
+                result = `${hours} hour${hours === 1 ? '' : 's'} ago`;
+            }
+            else {
+                const days = Math.round(ageMs / (24 * 60 * 60 * 1000));
+                result = `${days} day${days === 1 ? '' : 's'} ago`;
+            }
+        }
+    }
+    if (HUMAN_AGE_CACHE.size >= HUMAN_AGE_CACHE_LIMIT)
+        HUMAN_AGE_CACHE.clear();
+    HUMAN_AGE_CACHE.set(ageMs, result);
+    return result;
+}
 function rootLabel(projectRoot) {
     if (!projectRoot)
         return '';
     return basename(projectRoot);
 }
+/**
+ * Slice rid-statusline-24h-overlay (2026-08-10): format the 24h-mode
+ * overlay suffix appended after the existing `<baseMode>` token in
+ * the ACTIVE state. Returns `''` when the overlay is `null` (missing
+ * file / corrupt file / wrong shape — see `read24hOverlay`).
+ *
+ * Output shape (ASCII palette): ` . [24h-<lowercase-state>]`
+ * Output shape (unicode palette): ` · [24h-<lowercase-state>]`
+ *
+ * en-US only; i18n deferred to a future slice (PRD §Non-goals.5).
+ * The `[24h-...]` prefix is a deliberate marker so the user can
+ * visually distinguish a 24h-mode substate from a base-mode token
+ * like `[full-auto]`.
+ */
+export function format24hSuffix(overlay, palette, capability, noColor) {
+    if (!overlay)
+        return '';
+    const label = `[24h-${overlay.state.toLowerCase()}]`;
+    return `${palette.inlineSeparator}${brandRun(label, noColor, capability)}`;
+}
 /**
  * `formatShortSid` + `computeRootSuffix` were extracted to
  * `./skill-statusline-sid-suffix.ts` in the slice
@@ -223,14 +296,19 @@ function rootLabel(projectRoot) {
  * forced every bee role to render with a `↑<parent>` marker was removed
  * in this slice; the dual-skill layout above replaces it.
  */
-function renderActive(presence, palette, nowMs, capability, noColor, activeLeaf) {
+function renderActive(presence, palette, nowMs, capability, noColor, activeLeaf, twentyFourHourState) {
     if (!presence) {
         return `${palette.idle} ${palette.idleLabel}`;
     }
+    // Slice rid-statusline-24h-overlay (2026-08-10): the 24h suffix
+    // is appended on every active-return branch that carries a skill
+    // token. The `!presence` branch (idle mark, no skill token) is
+    // intentionally NOT modified — 24h overlays are active-only.
+    const suffix = format24hSuffix(twentyFourHourState, palette, capability, noColor);
     const attentionLabel = isAttentionGate(presence.gate);
     if (attentionLabel !== null) {
         // Attention gate — surface the warning glyph + human-readable label.
-        return `${palette.warning} ${brandRun(presence.skill, noColor, capability)}${palette.inlineSeparator}${brandRun(attentionLabel, noColor, capability)}`;
+        return `${palette.warning} ${brandRun(presence.skill, noColor, capability)}${palette.inlineSeparator}${brandRun(attentionLabel, noColor, capability)}${suffix}`;
     }
     const skill = presence.skill;
     const dot = renderActiveDot(capability, nowMs, noColor);
@@ -244,15 +322,25 @@ function renderActive(presence, palette, nowMs, capability, noColor, activeLeaf)
             ? ` ${brandRun(`(+${activeLeaf.pendingCount - 1})`, noColor, capability)}`
             : '';
         const sep = brandRun(' | ', noColor, capability);
-        return `${dot} ${leaf}${tail}${sep}${brandRun(skill, noColor, capability)}${modeToken}`;
+        return `${dot} ${leaf}${tail}${sep}${brandRun(skill, noColor, capability)}${modeToken}${suffix}`;
     }
-    return `${dot} ${brandRun(skill, noColor, capability)}${modeToken}`;
+    return `${dot} ${brandRun(skill, noColor, capability)}${modeToken}${suffix}`;
 }
 function renderStale(presence, ageMs, palette, capability, noColor) {
+    // Slice rid-statusline-stale-ux AC-1: stale presence belongs to a
+    // *previous* session (outer-session-mismatch). Line still emits the
+    // recorded skill name (per C-1 — `expect(out).toContain('peaks-code')`
+    // must keep passing), but uses `palette.idleStale` (new muted palette,
+    // distinct from idle and warning) and neutral
+    // `(previous session · <human age>)` suffix instead of legacy
+    // `stale <Nh>` token. ASCII capability replaces the `·` middle dot
+    // with `-` so byte-identical shape holds across encodings.
     const skill = presence?.skill ?? 'unknown';
-    const age = formatAge(ageMs);
-    const ageSuffix = age ? `${palette.inlineSeparator}${brandRun(age, noColor, capability)}` : '';
-    return `${palette.warning} ${brandRun(skill, noColor, capability)}${ageSuffix}`;
+    const age = formatHumanAge(ageMs);
+    const sep = capability === 'ascii' ? '-' : '·';
+    const label = age ? `(previous session ${sep} ${age})` : '(previous session)';
+    const ageSuffix = `${palette.inlineSeparator}${brandRun(label, noColor, capability)}`;
+    return `${palette.idleStale} ${brandRun(skill, noColor, capability)}${ageSuffix}`;
 }
 function renderInvalid(palette) {
     return `${palette.warning} ${palette.invalidMessage}`;
@@ -623,7 +711,7 @@ export function renderStatusLine(model, options, env) {
     else {
         switch (model.state) {
             case 'active':
-                line = `${brand} ${renderActive(model.presence, palette, nowMs, capability, noColor, model.activeLeaf)}${rootSuffix}`;
+                line = `${brand} ${renderActive(model.presence, palette, nowMs, capability, noColor, model.activeLeaf, model.twentyFourHourState)}${rootSuffix}`;
                 break;
             case 'stale':
                 line = `${brand} ${renderStale(model.presence, model.ageMs, palette, capability, noColor)}${rootSuffix}`;

package/dist/services/skills/skill-statusline-service.d.ts

@@ -41,6 +41,47 @@ export type StatusLineModel = {
      * existent root.
      */
     sessionId: string | null;
+    /**
+     * Slice rid-statusline-24h-overlay (2026-08-10): the 24h-mode
+     * overlay snapshot read from `.peaks/_runtime/<sid>/24h-state.json`,
+     * or `null` when no file exists / file is corrupt / file has wrong
+     * shape. The renderer reads this to append `[24h-<state>]` after
+     * the existing `<baseMode>` token in the ACTIVE state only.
+     *
+     * Always present (never undefined). `null` means "no overlay" —
+     * the renderer skips the suffix without re-reading disk.
+     */
+    twentyFourHourState: TwentyFourHourOverlay | null;
+};
+/**
+ * Slice rid-statusline-24h-overlay (2026-08-10): minimal overlay
+ * type returned by `read24hOverlay`. The renderer only consumes
+ * `state` (to format `[24h-<state.toLowerCase()>]`). The canonical
+ * schema at `src/services/24h-mode/state.ts:55-66` carries additional
+ * fields (`attempts: Record<DecisionKey, number>`, `enteredAt`,
+ * `checkpoints`, etc.) but the overlay is deliberately MINIMAL —
+ * it tolerates forward compatibility with new states the writer
+ * may add, and it never throws on malformed shapes (PRD AC-3:
+ * graceful null on any invalid input).
+ */
+export type TwentyFourHourOverlay = {
+    state: string;
 };
+/**
+ * Slice rid-statusline-24h-overlay (2026-08-10): name-distinct from
+ * the canonical `read24hState` in `src/services/24h-mode/store.ts:108`.
+ * The canonical reader calls `coerceSnapshot` (which throws on
+ * malformed shapes via `24H_STATE_INVALID`); this overlay reader
+ * returns `null` for ANY malformed shape (per PRD AC-3 — never
+ * throw across the statusline boundary).
+ *
+ * Returns null when:
+ *   - `projectRoot` or `sessionId` is empty
+ *   - the file does not exist (ENOENT)
+ *   - JSON.parse fails (corrupt file)
+ *   - root is not a non-array object
+ *   - `state` is missing, non-string, or empty string
+ */
+export declare function read24hOverlay(projectRoot: string, sessionId: string): TwentyFourHourOverlay | null;
 export declare function parseStatusLineStdin(raw: string): StatusLineStdin | null;
 export declare function buildStatusLineModel(stdin: StatusLineStdin | null, nowMs: number): StatusLineModel;

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

@@ -1,4 +1,5 @@
-import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { findProjectRoot } from '../config/config-safety.js';
 import { decideCompactStatusline } from '../compact-statusline/compact-statusline-service.js';
 import { getSessionIdCanonical } from '../session/session-manager.js';
@@ -30,6 +31,48 @@ import { readActiveDispatchIndex } from '../dispatch/dispatch-record-writer.js';
  * documented back-compat path.
  */
 const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+/**
+ * Slice rid-statusline-24h-overlay (2026-08-10): name-distinct from
+ * the canonical `read24hState` in `src/services/24h-mode/store.ts:108`.
+ * The canonical reader calls `coerceSnapshot` (which throws on
+ * malformed shapes via `24H_STATE_INVALID`); this overlay reader
+ * returns `null` for ANY malformed shape (per PRD AC-3 — never
+ * throw across the statusline boundary).
+ *
+ * Returns null when:
+ *   - `projectRoot` or `sessionId` is empty
+ *   - the file does not exist (ENOENT)
+ *   - JSON.parse fails (corrupt file)
+ *   - root is not a non-array object
+ *   - `state` is missing, non-string, or empty string
+ */
+export function read24hOverlay(projectRoot, sessionId) {
+    if (!projectRoot || !sessionId)
+        return null;
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, '24h-state.json');
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        // ENOENT, EACCES, EISDIR — all treated as "no overlay"
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // corrupt JSON — graceful null (PRD AC-3)
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    if (typeof obj['state'] !== 'string' || obj['state'].length === 0)
+        return null;
+    return { state: obj['state'] };
+}
 function resolveCwdFromStdin(stdin) {
     const fromWorkspace = stdin?.workspace?.current_dir ?? stdin?.workspace?.project_dir;
     if (typeof fromWorkspace === 'string' && fromWorkspace.length > 0) {
@@ -234,16 +277,16 @@ export function buildStatusLineModel(stdin, nowMs) {
         }
     }
     if (projectRoot === null) {
-        return { state: 'idle', projectRoot: null, presence: null, ageMs: null, compact, activeLeaf: null, sessionId: null };
+        return { state: 'idle', projectRoot: null, presence: null, ageMs: null, compact, activeLeaf: null, sessionId: null, twentyFourHourState: null };
     }
     // callerId resolves the read-side isolation; back-compat is `null`.
     const callerId = resolveCallerId(stdin);
     const { presence, invalid } = readPresenceReadOnly(projectRoot, callerId);
     if (invalid) {
-        return { state: 'invalid-presence', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null, sessionId };
+        return { state: 'invalid-presence', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null, sessionId, twentyFourHourState: null };
     }
     if (presence === null) {
-        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null, sessionId };
+        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null, sessionId, twentyFourHourState: null };
     }
     // Session binding: when the presence was stamped with a Claude session id and
     // the live session (from stdin) is a different one, the recorded skill belongs
@@ -252,7 +295,7 @@ export function buildStatusLineModel(stdin, nowMs) {
     // fall back to the time-based behavior below for backward compatibility.
     const liveSessionId = typeof stdin?.session_id === 'string' && stdin.session_id.length > 0 ? stdin.session_id : null;
     if (presence.claudeSessionId && liveSessionId && presence.claudeSessionId !== liveSessionId) {
-        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null, sessionId };
+        return { state: 'idle', projectRoot, presence: null, ageMs: null, compact, activeLeaf: null, sessionId, twentyFourHourState: null };
     }
     const setAtMs = presence.setAt ? Date.parse(presence.setAt) : Number.NaN;
     const ageMs = Number.isNaN(setAtMs) ? null : nowMs - setAtMs;
@@ -268,7 +311,14 @@ export function buildStatusLineModel(stdin, nowMs) {
     catch {
         activeLeaf = null;
     }
-    return { state, projectRoot, presence, ageMs, compact, activeLeaf, sessionId };
+    // Slice rid-statusline-24h-overlay (2026-08-10): read the 24h-mode
+    // overlay snapshot ONLY when state === 'active'. Stale / idle /
+    // invalid-presence / idle-via-outer-mismatch never carry the suffix
+    // (per PRD §Non-goals.6 — "不在 idle / stale / invalid-presence
+    // 状态下 overlay 24h suffix"). When projectRoot or sessionId is
+    // missing, return null without re-reading disk.
+    const twentyFourHourState = state === 'active' ? read24hOverlay(projectRoot, sessionId ?? '') : null;
+    return { state, projectRoot, presence, ageMs, compact, activeLeaf, sessionId, twentyFourHourState };
 }
 /**
  * Read-only compact state resolver. Resolves the canonical session id for the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.17",
+  "version": "4.0.18",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,9 +101,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-mut": "0.1.20",
-    "peaks-loop-shared-channel": "0.0.24",
-    "peaks-loop-shared": "0.0.48"
+    "peaks-loop-mut": "0.1.21",
+    "peaks-loop-shared": "0.0.49",
+    "peaks-loop-shared-channel": "0.0.25"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",