peaks-cli 1.1.2 → 1.2.1

package/dist/src/cli/program.js

@@ -1,4 +1,7 @@
+import { readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { Command } from 'commander';
+import { skillsDir } from '../shared/paths.js';
 import { CLI_VERSION } from '../shared/version.js';
 import { registerCoreAndArtifactCommands } from './commands/core-artifact-commands.js';
 import { registerWorkflowCommands } from './commands/workflow-commands.js';
@@ -10,6 +13,9 @@ import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
+import { registerSopCommands } from './commands/sop-commands.js';
+import { registerGateCommands } from './commands/gate-commands.js';
+import { registerHooksCommands } from './commands/hooks-commands.js';
 import { registerStatusLineCommands } from './commands/statusline-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
@@ -18,7 +24,14 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     const program = new Command();
     program
         .name('peaks')
-        .description('Peaks CLI and short skill family runtime manager')
+        .description(`Peaks CLI ${CLI_VERSION} — workflow-gating CLI + skill family for Claude Code
+
+Run peaks (no arguments) for a quickstart. You likely want one of:
+  peaks doctor     check your environment
+  peaks skill      list or manage skills
+  peaks sop        author your own workflow gates
+  peaks hooks      install the un-bypassable gate-enforcement hook
+  peaks gate       enforce/bypass SOP gates on Bash commands`)
         .configureOutput({
         writeOut: (text) => io.stdout(text.trimEnd()),
         writeErr: (text) => io.stderr(text.trimEnd())
@@ -26,9 +39,38 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
         .version(CLI_VERSION, '-v, --version')
         .option('-V', 'output the version number')
         .action(() => {
-        if (program.opts().V) {
+        const opts = program.opts();
+        if (opts.V) {
             io.stdout(CLI_VERSION);
+            return;
         }
+        // Count bundled skills by reading the skills dir directly (synchronous so
+        // the quickstart renders instantly — no import/async overhead on startup).
+        let skillCount = 0;
+        const skillsPath = skillsDir;
+        try {
+            if (existsSync(skillsPath)) {
+                skillCount = readdirSync(skillsPath, { withFileTypes: true })
+                    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+                    .filter((entry) => existsSync(join(skillsPath, entry.name, 'SKILL.md')))
+                    .length;
+            }
+        }
+        catch { /* disk read is best-effort; zero skills is still truthful */ }
+        io.stdout(`Peaks CLI ${CLI_VERSION}  ·  ${skillCount} skills ready
+
+  Peaks is a workflow-gating CLI + skill family for Claude Code.
+  It turns "don't skip steps" into hard enforcement — gates that block
+  advancement in-conversation, un-bypassably.
+
+  Before diving into a project, two things worth doing now:
+
+    peaks doctor             check your environment in one glance
+    peaks-sop                <<< ask this skill to author your first SOP
+
+  Or jump straight in:
+    peaks sop init --id my-flow --apply && peaks hooks install
+`);
     })
         .exitOverride();
     registerCoreAndArtifactCommands(program, io);
@@ -41,6 +83,9 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     registerRequestCommands(program, io);
     registerScanCommands(program, io);
     registerShadcnCommands(program, io);
+    registerSopCommands(program, io);
+    registerGateCommands(program, io);
+    registerHooksCommands(program, io);
     registerStatusLineCommands(program, io);
     registerUnderstandCommands(program, io);
     registerWorkspaceCommands(program, io);

package/dist/src/services/dashboard/project-dashboard-service.js

@@ -74,8 +74,10 @@ function buildCapabilitiesSummary(sampleSize) {
         }))
     };
 }
-function buildSkillPresenceSummary(presence) {
-    const resolved = presence === undefined ? getSkillPresence() : presence;
+function buildSkillPresenceSummary(presence, projectRoot) {
+    // When the caller doesn't supply presence, resolve it from the dashboard's
+    // project root rather than the process cwd.
+    const resolved = presence === undefined ? getSkillPresence(projectRoot) : presence;
     if (resolved === null) {
         return { active: false, fresh: true };
     }
@@ -126,6 +128,6 @@ export async function loadProjectDashboard(options) {
         doctor: doctorAndRunbook.doctor,
         runbookHealth: doctorAndRunbook.runbookHealth,
         capabilities: buildCapabilitiesSummary(sampleSize),
-        skillPresence: buildSkillPresenceSummary(options.skillPresence)
+        skillPresence: buildSkillPresenceSummary(options.skillPresence, options.projectRoot)
     };
 }

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

@@ -25,5 +25,9 @@ export type DoctorOptions = {
     skillPresenceProbe?: () => SkillPresence | null;
     skillPresenceFreshnessThresholdMs?: number;
     statusLineInstalledProbe?: () => boolean;
+    /** Returns true when a Peaks workspace session (.peaks/.session.json) exists. */
+    workspaceInitializedProbe?: () => boolean;
+    /** Platform string (defaults to process.platform); injectable for tests. */
+    platform?: NodeJS.Platform;
 };
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

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

@@ -10,6 +10,7 @@ import { loadSkillRegistry } from '../skills/skill-registry.js';
 import { getSkillPresence } from '../skills/skill-presence-service.js';
 import { planStatusLineInstall } from '../skills/statusline-settings-service.js';
 import { findProjectRoot } from '../config/config-safety.js';
+import { CLI_VERSION } from '../../shared/version.js';
 const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
 const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 function defaultCodegraphProbe() {
@@ -26,15 +27,29 @@ function defaultCodegraphProbe() {
 }
 function defaultStatusLineInstalledProbe() {
     const projectRoot = findProjectRoot(process.cwd());
-    if (projectRoot === null)
-        return false;
+    // Check both scopes: a user may have installed the statusLine globally, which
+    // the project-only check would miss and falsely report as "not installed".
     try {
-        return planStatusLineInstall('project', projectRoot).alreadyInstalled;
+        if (projectRoot !== null && planStatusLineInstall('project', projectRoot).alreadyInstalled) {
+            return true;
+        }
+    }
+    catch {
+        /* fall through to global */
+    }
+    try {
+        return planStatusLineInstall('global').alreadyInstalled;
     }
     catch {
         return false;
     }
 }
+function defaultWorkspaceInitializedProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null)
+        return false;
+    return existsSync(join(projectRoot, '.peaks', '.session.json'));
+}
 const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+sync[^\n]*--apply/,
     /peaks\s+memory\s+extract[^\n]*--apply/,
@@ -203,6 +218,34 @@ export async function runDoctor(options = {}) {
             }
         }
     }
+    // Workspace guard: an active workflow presence (peaks-solo) with no workspace
+    // session means the skill was anchored but `peaks workspace init` never ran —
+    // the #1 reported failure where .peaks/ artifacts are never created. This
+    // turns the SKILL.md "MUST create the workspace" prose into an executable check.
+    const workspaceProbe = options.workspaceInitializedProbe ?? defaultWorkspaceInitializedProbe;
+    let workspaceInitialized = false;
+    try {
+        workspaceInitialized = workspaceProbe();
+    }
+    catch {
+        workspaceInitialized = false;
+    }
+    if (presence !== null && !workspaceInitialized) {
+        checks.push({
+            id: 'skill-presence:workspace',
+            ok: false,
+            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/.session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
+        });
+    }
+    else {
+        checks.push({
+            id: 'skill-presence:workspace',
+            ok: true,
+            message: presence === null
+                ? 'No active skill presence; workspace guard not applicable'
+                : `Workspace session present for active skill ${presence.skill}`
+        });
+    }
     // Discoverability nudge: when a skill is actively orchestrating but the
     // out-of-band statusLine isn't installed, the user has no terminal-level
     // signal that Peaks is in control. Suggest installing it (non-failing).
@@ -230,6 +273,26 @@ export async function runDoctor(options = {}) {
                 : 'Peaks statusLine not installed (no active skill; install optional)'
         });
     }
+    // Runtime/platform diagnostic for the "statusLine shows nothing" reports.
+    // Surfaces (a) the running peaks version — a stale global install predating
+    // the statusLine feature is a common cause — and (b) on Windows, the fact that
+    // the bare `peaks statusline` command must resolve in the shell Claude Code
+    // spawns, which fails when the npm global bin dir is not on that shell's PATH.
+    const platform = options.platform ?? process.platform;
+    if (platform === 'win32') {
+        checks.push({
+            id: 'statusline:runtime',
+            ok: true,
+            message: `peaks ${CLI_VERSION} (win32): if the statusLine shows nothing in git bash, verify \`peaks\` resolves on PATH in the shell Claude Code uses (run \`peaks -v\` there), reinstall globally with \`npm i -g peaks-cli@latest\` if the version is older than ${CLI_VERSION}, then re-run \`peaks statusline install\` and reload Claude Code`
+        });
+    }
+    else {
+        checks.push({
+            id: 'statusline:runtime',
+            ok: true,
+            message: `peaks ${CLI_VERSION} (${platform}): statusLine command is \`peaks statusline\``
+        });
+    }
     const probe = options.codegraphProbe ?? defaultCodegraphProbe;
     try {
         const result = probe();

package/dist/src/services/mode/mode-enforcement.js

@@ -31,7 +31,8 @@ export class ConfirmationRequiredError extends Error {
     }
 }
 export async function requireUserConfirmation(options) {
-    const presence = getSkillPresence();
+    // Resolve presence from the project being operated on, not the process cwd.
+    const presence = getSkillPresence(options.projectRoot);
     if (!presence?.mode) {
         return;
     }

package/dist/src/services/skills/hooks-settings-service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Installs (and removes) the Peaks gate-enforcement PreToolUse hook in a Claude
+ * Code settings.json. The hook runs `peaks gate enforce` before every Bash call;
+ * when a SOP guard's gates fail it returns `permissionDecision: "deny"`, which
+ * blocks the tool call BEFORE Claude Code's permission checks — making the gate
+ * un-bypassable by the agent (it holds even under --dangerously-skip-permissions).
+ *
+ * Installation is an EXPLICIT user command (never postinstall): skills describe,
+ * the CLI performs side effects. Writes preserve all other settings keys and any
+ * other hooks, reject symlinked targets, and use an atomic rename so a partial
+ * write can never corrupt the settings file. Our entry is merged into (not
+ * replacing) the existing `hooks.PreToolUse` array and is identified by a
+ * sentinel substring in its command, so install is idempotent and uninstall
+ * removes only our own entry.
+ */
+export type HookScope = 'project' | 'global';
+/** The hook command written into settings. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
+export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
+/** Substring that identifies a Peaks-managed PreToolUse hook entry. */
+export declare const HOOK_SENTINEL = "peaks gate enforce";
+export type HookInstallPlan = {
+    scope: HookScope;
+    settingsPath: string;
+    exists: boolean;
+    alreadyInstalled: boolean;
+    desiredCommand: string;
+};
+export type HookInstallResult = HookInstallPlan & {
+    applied: boolean;
+};
+export type HookRemoveResult = {
+    scope: HookScope;
+    settingsPath: string;
+    removed: boolean;
+};
+export type HookStatus = {
+    scope: HookScope;
+    settingsPath: string;
+    exists: boolean;
+    installed: boolean;
+};
+export declare function planHookInstall(scope: HookScope, projectRoot?: string): HookInstallPlan;
+export declare function applyHookInstall(scope: HookScope, projectRoot?: string): HookInstallResult;
+export declare function removeHookInstall(scope: HookScope, projectRoot?: string): HookRemoveResult;
+export declare function readHookStatus(scope: HookScope, projectRoot?: string): HookStatus;

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

@@ -0,0 +1,167 @@
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+/** The hook command written into settings. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
+export const HOOK_ENFORCE_COMMAND = 'peaks gate enforce --project "${CLAUDE_PROJECT_DIR}"';
+/** Substring that identifies a Peaks-managed PreToolUse hook entry. */
+export const HOOK_SENTINEL = 'peaks gate enforce';
+const HOOK_MATCHER = 'Bash';
+function isInsidePath(childPath, parentPath) {
+    const rel = relative(parentPath, childPath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function resolveSettingsRoot(scope, projectRoot) {
+    if (scope === 'global')
+        return resolve(homedir());
+    if (!projectRoot) {
+        throw new Error('Project scope requires a project root');
+    }
+    return resolve(projectRoot);
+}
+function resolveSettingsPath(scope, projectRoot) {
+    return join(resolveSettingsRoot(scope, projectRoot), '.claude', 'settings.json');
+}
+function assertSafeSettingsPath(scope, root, settingsPath) {
+    const claudeDir = join(root, '.claude');
+    if (existsSync(claudeDir) && lstatSync(claudeDir).isSymbolicLink()) {
+        throw new Error('.claude directory must not be a symlink');
+    }
+    if (existsSync(settingsPath)) {
+        if (lstatSync(settingsPath).isSymbolicLink()) {
+            throw new Error('settings.json must not be a symlink');
+        }
+        const realRoot = realpathSync(root);
+        if (!isInsidePath(realpathSync(settingsPath), realRoot)) {
+            throw new Error(`settings.json must stay inside the ${scope} root`);
+        }
+    }
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    const fd = openSync(settingsPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const raw = readFileSync(fd, 'utf8').trim();
+        if (raw.length === 0)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('settings.json must contain a JSON object');
+        }
+        return parsed;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function atomicWriteJson(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    mkdirSync(dir, { recursive: true });
+    const tempPath = join(dir, `.settings.${randomUUID()}.tmp`);
+    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tempPath, settingsPath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // best effort cleanup
+        }
+        throw error;
+    }
+}
+/** Read the existing PreToolUse matcher entries (tolerant of any prior shape). */
+function readPreToolUse(settings) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return [];
+    const pre = hooks.PreToolUse;
+    return Array.isArray(pre) ? pre : [];
+}
+function entryIsPeaksManaged(entry) {
+    const handlers = Array.isArray(entry?.hooks) ? entry.hooks : [];
+    return handlers.length > 0 && handlers.every((h) => typeof h?.command === 'string' && h.command.includes(HOOK_SENTINEL));
+}
+function isInstalled(settings) {
+    return readPreToolUse(settings).some(entryIsPeaksManaged);
+}
+export function planHookInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    return { scope, settingsPath, exists, alreadyInstalled: isInstalled(settings), desiredCommand: HOOK_ENFORCE_COMMAND };
+}
+/** Merge our PreToolUse entry into settings, preserving all other keys and hooks. */
+function withHookInstalled(settings) {
+    const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
+        ? settings.hooks
+        : {};
+    const preToolUse = readPreToolUse(settings);
+    const ourEntry = { matcher: HOOK_MATCHER, hooks: [{ type: 'command', command: HOOK_ENFORCE_COMMAND }] };
+    return {
+        ...settings,
+        hooks: { ...existingHooks, PreToolUse: [...preToolUse, ourEntry] }
+    };
+}
+export function applyHookInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    if (isInstalled(settings)) {
+        return { scope, settingsPath, exists, alreadyInstalled: true, desiredCommand: HOOK_ENFORCE_COMMAND, applied: false };
+    }
+    atomicWriteJson(settingsPath, withHookInstalled(settings));
+    return { scope, settingsPath, exists, alreadyInstalled: false, desiredCommand: HOOK_ENFORCE_COMMAND, applied: true };
+}
+export function removeHookInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    if (!existsSync(settingsPath)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const settings = readSettings(settingsPath);
+    const preToolUse = readPreToolUse(settings);
+    const kept = preToolUse.filter((entry) => !entryIsPeaksManaged(entry));
+    if (kept.length === preToolUse.length) {
+        return { scope, settingsPath, removed: false };
+    }
+    const existingHooks = settings.hooks ?? {};
+    const nextHooks = { ...existingHooks };
+    if (kept.length > 0) {
+        nextHooks.PreToolUse = kept;
+    }
+    else {
+        delete nextHooks.PreToolUse;
+    }
+    const nextSettings = { ...settings };
+    if (Object.keys(nextHooks).length > 0) {
+        nextSettings.hooks = nextHooks;
+    }
+    else {
+        delete nextSettings.hooks;
+    }
+    atomicWriteJson(settingsPath, nextSettings);
+    return { scope, settingsPath, removed: true };
+}
+export function readHookStatus(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readSettings(settingsPath) : {};
+    return { scope, settingsPath, exists, installed: isInstalled(settings) };
+}

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

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

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

@@ -10,6 +10,16 @@ export const VALID_SKILL_PRESENCE_MODES = [
 export function isSkillPresenceMode(value) {
     return VALID_SKILL_PRESENCE_MODES.includes(value);
 }
+/**
+ * The current Claude Code session id, exposed to Bash tool calls via the
+ * CLAUDE_CODE_SESSION_ID environment variable. Stamping it onto the presence
+ * file lets the read-only status line tell whether the recorded skill belongs
+ * to the live session (show it) or a previous one (render idle).
+ */
+function getCurrentClaudeSessionId() {
+    const value = process.env.CLAUDE_CODE_SESSION_ID;
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
 const PRESENCE_FILE = '.peaks/.active-skill.json';
 const SESSION_FILE = '.peaks/.session.json';
 function resolveProjectRoot(override) {
@@ -40,12 +50,14 @@ export function exportSkillPresence(projectRootOverride) {
 export function setSkillPresence(skill, mode, gate, projectRootOverride) {
     const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
     const sessionId = getCurrentSessionId(projectRootOverride);
+    const claudeSessionId = getCurrentClaudeSessionId();
     const now = new Date().toISOString();
     const presence = {
         skill,
         ...(validatedMode ? { mode: validatedMode } : {}),
         ...(gate ? { gate } : {}),
         ...(sessionId ? { sessionId } : {}),
+        ...(claudeSessionId ? { claudeSessionId } : {}),
         setAt: now,
         lastHeartbeat: now
     };

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

@@ -4,6 +4,7 @@ export type StatusLineStdin = {
         project_dir?: string;
     };
     cwd?: string;
+    session_id?: string;
 };
 export type StatusLineState = 'active' | 'idle' | 'stale' | 'invalid-presence';
 export type StatusLinePresence = {
@@ -11,6 +12,7 @@ export type StatusLinePresence = {
     mode?: string;
     gate?: string;
     setAt?: string;
+    claudeSessionId?: string;
 };
 export type StatusLineModel = {
     state: StatusLineState;

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

@@ -65,7 +65,8 @@ function readPresenceReadOnly(projectRoot) {
                 skill: candidate.skill,
                 ...(typeof candidate.mode === 'string' ? { mode: candidate.mode } : {}),
                 ...(typeof candidate.gate === 'string' ? { gate: candidate.gate } : {}),
-                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {})
+                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {}),
+                ...(typeof candidate.claudeSessionId === 'string' ? { claudeSessionId: candidate.claudeSessionId } : {})
             },
             invalid: false
         };
@@ -87,6 +88,15 @@ export function buildStatusLineModel(stdin, nowMs) {
     if (presence === null) {
         return { state: 'idle', projectRoot, presence: null, ageMs: 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
+    // to a previous session — render idle instead of a stale "active" skill. When
+    // either id is absent (legacy presence, or harness that omits session_id) we
+    // 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 };
+    }
     const setAtMs = presence.setAt ? Date.parse(presence.setAt) : Number.NaN;
     const ageMs = Number.isNaN(setAtMs) ? null : nowMs - setAtMs;
     const state = ageMs !== null && ageMs > STALE_THRESHOLD_MS ? 'stale' : 'active';

package/dist/src/services/sop/gate-enforce-service.d.ts

@@ -0,0 +1,33 @@
+import type { BlockedGate } from './sop-advance-service.js';
+export type MatchedGuard = {
+    sopId: string;
+    phase: string;
+    /** The non-passing gates that block this phase's guarded action. */
+    failing: BlockedGate[];
+};
+export type EnforceDecision = {
+    decision: 'allow';
+    bypassed?: boolean;
+    warnings?: string[];
+} | {
+    decision: 'deny';
+    reason: string;
+    matched: MatchedGuard[];
+};
+export declare class GateBypassError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Record a one-shot bypass token for `<sopId>:<phase>` in this project. The next
+ * `enforceBashCommand` that the transition blocks consumes it and allows once.
+ * Capped per-project-per-SOP by MAX_BYPASSES_PER_SESSION.
+ */
+export declare function recordGateBypass(projectRoot: string, sopId: string, phase: string, reason: string): {
+    count: number;
+};
+/**
+ * Decide whether a Bash command may run. Pure given the filesystem; never throws
+ * (fail-open on any internal error). Returns allow/deny for the PreToolUse hook.
+ */
+export declare function enforceBashCommand(projectRoot: string, command: string): Promise<EnforceDecision>;