peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/web-stop-command.js

@@ -0,0 +1,59 @@
+// src/cli/commands/web-stop-command.ts
+//
+// `peaks web stop` — stop this session's daemon and clear its records. Split
+// out of `web-lifecycle-commands.ts`; the verb name, its options, the
+// `stopped`-means-gone contract and the warning lines are unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { stopDaemon } from '../../services/web/daemon-supervisor.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { noSession, resolveSession } from './web-command-shared.js';
+/** Everything `stop` did NOT clean, said out loud rather than left implicit. */
+function stopWarnings(result) {
+    const warnings = [];
+    const stuck = result.pids.length - result.stopped;
+    if (stuck > 0) {
+        warnings.push(`${String(stuck)} daemon process(es) did not exit after the stop request; they are recorded, ` +
+            'so a later `peaks web stop` can try again');
+    }
+    if (result.orphanedPids.length > 0) {
+        warnings.push(`${String(result.orphanedPids.length)} daemon instance(s) are alive but could not be proven ` +
+            "to be this session's daemon (no authenticated identity); the processes were left running, " +
+            'because a pid that cannot be proven is never signalled, and their records are kept so ' +
+            '`peaks web status` and a later `stop` still see them');
+    }
+    return warnings;
+}
+/**
+ * Stop the daemon and clear its records. `stopped` counts the daemons whose
+ * process is confirmed GONE by return — not merely the ones we signalled — so a
+ * caller that checks the process table right after this returns is not racing
+ * the teardown (AC6).
+ */
+export async function runWebStop(io, asJson) {
+    const command = 'peaks.web.stop';
+    try {
+        const session = resolveSession();
+        if (session === null) {
+            printResult(io, noSession(command), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const result = await stopDaemon(session.projectRoot, session.sessionId);
+        printResult(io, ok(command, {
+            stopped: result.stopped,
+            pids: [...result.pids],
+            orphanedPids: [...result.orphanedPids]
+        }, stopWarnings(result)), asJson);
+    }
+    catch (error) {
+        printResult(io, fail(command, 'WEB_STOP_FAILED', `peaks web stop failed: ${getErrorMessage(error)}`, {}, []), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWebStopCommand(web, io) {
+    addJsonOption(web
+        .command('stop')
+        .description("Stop this session's web daemon and close its browser. Scoped to this project root and " +
+        'session; another worktree is untouched, and a process that cannot be proven to be this ' +
+        "session's daemon is left running rather than signalled.")).action((options) => runWebStop(io, options.json === true));
+}

package/dist/cli/commands/web-verb-specs.d.ts

@@ -0,0 +1,18 @@
+import type { WebOp } from '../../services/web/web-protocol.js';
+export interface WebVerbSpec {
+    readonly name: string;
+    readonly op: WebOp;
+    readonly description: string;
+    readonly argument: {
+        readonly name: string;
+        readonly description: string;
+    } | null;
+    readonly takesProfile?: true;
+    readonly toArgs: (positional: readonly (string | undefined)[], profile: string | undefined) => Record<string, unknown>;
+}
+/**
+ * The option text names the read-only half out loud: a caller who browses with a
+ * profile must not assume the profile was refreshed by it.
+ */
+export declare const PROFILE_OPTION_DESCRIPTION: string;
+export declare const WEB_VERBS: readonly WebVerbSpec[];

package/dist/cli/commands/web-verb-specs.js

@@ -0,0 +1,66 @@
+// src/cli/commands/web-verb-specs.ts
+//
+// The six S1 `peaks web open|text|snap|click|shot|metrics` verbs, as data.
+// Split out of `web-commands.ts`: the table is what `registerWebCommands`
+// iterates, and keeping it beside the registration loop is what made that
+// function's own body read as the whole command surface.
+//
+// `--profile <name>` is declared on `open` and nowhere else (design §2 lists it
+// only there). Any other verb taking a profile would invent behaviour nobody
+// asked for and multiply the isolation questions for no requested benefit.
+/**
+ * The option text names the read-only half out loud: a caller who browses with a
+ * profile must not assume the profile was refreshed by it.
+ */
+export const PROFILE_OPTION_DESCRIPTION = 'navigate with a saved login profile (`peaks web login --profile <name>`): [a-z0-9._-], ' +
+    '1-64 chars, upper case folds to lower. The profile is READ-ONLY here — this run loads it ' +
+    'and never writes it back, so browser activity is not saved into it.';
+export const WEB_VERBS = [
+    {
+        name: 'open',
+        op: 'open',
+        description: 'Navigate the dispatch browser context to <url>. With --profile, the page loads that ' +
+            'saved login.',
+        argument: { name: '<url>', description: 'absolute URL to load' },
+        takesProfile: true,
+        toArgs: (positional, profile) => ({
+            url: positional[0] ?? '',
+            ...(profile === undefined ? {} : { profile })
+        })
+    },
+    {
+        name: 'text',
+        op: 'text',
+        description: 'Return the visible text of the page (or of [selector]), byte-capped.',
+        argument: { name: '[selector]', description: 'CSS selector (default: body)' },
+        toArgs: (positional) => ({ selector: positional[0] })
+    },
+    {
+        name: 'snap',
+        op: 'snap',
+        description: 'Return a pruned ARIA snapshot of the page (or of [selector]), byte-capped.',
+        argument: { name: '[selector]', description: 'CSS selector (default: body)' },
+        toArgs: (positional) => ({ selector: positional[0] })
+    },
+    {
+        name: 'click',
+        op: 'click',
+        description: 'Click the element matching <selector> in the dispatch browser context.',
+        argument: { name: '<selector>', description: 'CSS selector to click' },
+        toArgs: (positional) => ({ selector: positional[0] ?? '' })
+    },
+    {
+        name: 'shot',
+        op: 'shot',
+        description: 'Screenshot the page (or [selector]) into the session web/ directory.',
+        argument: { name: '[selector]', description: 'CSS selector (default: full page)' },
+        toArgs: (positional) => ({ selector: positional[0] })
+    },
+    {
+        name: 'metrics',
+        op: 'metrics',
+        description: 'Return Core Web Vitals for the dispatch page, or why they are unavailable.',
+        argument: null,
+        toArgs: () => ({})
+    }
+];

package/dist/cli/commands/workflow-command-shared.d.ts

@@ -0,0 +1,102 @@
+export interface WorkflowInitOptions {
+    readonly skill?: string;
+    readonly parentWorkflow?: string;
+    readonly workflowId?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowGraphShowOptions {
+    readonly workflow?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowGraphListOptions {
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowNodePrepareOptions {
+    readonly workflow?: string;
+    readonly node?: string;
+    readonly kind?: string;
+    readonly label?: string;
+    readonly dependsOn?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowNodeAckOptions {
+    readonly workflow?: string;
+    readonly node?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowNodeMarkLostOptions {
+    readonly workflow?: string;
+    readonly node?: string;
+    readonly reason?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly json?: boolean;
+}
+export interface WorkflowTerminalizeOptions {
+    readonly workflow?: string;
+    readonly reason?: string;
+    readonly project?: string;
+    readonly sessionId?: string;
+    readonly requireConsumed?: boolean;
+    readonly json?: boolean;
+}
+/**
+ * Base 36, so a `Date.now()` suffix stays short enough to read in a transcript.
+ * Named rather than inlined because two verbs generate ids this way.
+ */
+export declare const GENERATED_ID_RADIX = 36;
+export declare function deriveCallerId(): string;
+export declare function deriveProjectRoot(options: {
+    project?: string;
+}): string;
+/**
+ * The literal that means "no session could be resolved". Kept as a named
+ * constant because three call sites now have to ASK whether resolution
+ * failed rather than consume the value as if it were an id.
+ */
+export declare const UNKNOWN_SESSION_ID = "unknown-sid";
+/**
+ * Resolve the session id for every `workflow *` command.
+ *
+ * Tier order (matches the idiom every other command family in this CLI
+ * already uses — see `job-commands.ts:85`, `container-commands.ts:138`):
+ *
+ *   1. `--session-id <sid>`             — explicit wins
+ *   2. `PEAKS_SESSION_ID` env var       — scripted / sub-process callers
+ *   3. `getCurrentSessionId(projectRoot)` — this caller's OWN binding
+ *      (`callers/<callerId>.json`) falling back to the project-global
+ *      `.peaks/_runtime/session.json`, the same resolver `peaks session
+ *      info --active` and `peaks session checkpoint` use
+ *   4. `unknown-sid`                    — nothing is bound
+ *
+ * Tier 3 was MISSING until 2026-09-15 (S6), and its absence is the whole
+ * defect: `workflow init` resolved on tiers 1–2 only, so with no flag and no
+ * env var it wrote the graph into `.peaks/_runtime/unknown-sid/graphs/`
+ * regardless of what the binding file said. `peaks workflow node prepare`
+ * then ran under the CORRECT session dir and reported `PEAKS_GRAPH_NOT_FOUND`
+ * — the graph it was asking for had been written one bucket over. The bucket
+ * accumulated artifacts from at least 4 distinct caller ids between 2026-09-01
+ * and 2026-09-15, i.e. it had never worked for anyone.
+ *
+ * The same prior-art sweep (`.peaks/memory/archived/2026-06-26-unknown-sid-root-cause.md`)
+ * converted six inline `?? 'unknown-sid'` sites to this 4-tier chain;
+ * `workflow-lifecycle-commands.ts` was missed. This is that site.
+ *
+ * The project root passed to tier 3 goes through the same `findProjectRoot`
+ * walk `session info` uses, so a command run from a SUBDIRECTORY of the
+ * project resolves the project's binding instead of `cwd`'s (which has none).
+ */
+export declare function deriveSessionId(options: {
+    sessionId?: string;
+    project?: string;
+}): string;

package/dist/cli/commands/workflow-command-shared.js

@@ -0,0 +1,74 @@
+// src/cli/commands/workflow-command-shared.ts
+//
+// What every `peaks workflow *` lifecycle verb shares: the option vocabulary,
+// the caller/project/session derivation and the generated-id radix. Split out of
+// `workflow-lifecycle-commands.ts`; the derivation tiers, the literal
+// `unknown-sid` and every option name are unchanged.
+import { getErrorMessage, fail } from 'peaks-loop-shared/result';
+import { resolveCallerId } from '../../services/session/resolve-caller-id.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+/**
+ * Base 36, so a `Date.now()` suffix stays short enough to read in a transcript.
+ * Named rather than inlined because two verbs generate ids this way.
+ */
+export const GENERATED_ID_RADIX = 36;
+export function deriveCallerId() {
+    try {
+        return resolveCallerId({});
+    }
+    catch (err) {
+        // The thrown value is the `fail` envelope, not an `Error`: the callers'
+        // catch reads `.code` off it. Left as-is — changing the thrown type would
+        // change the envelope those callers render.
+        throw fail('workflow.init', 'PEAKS_CALLER_NOT_RESOLVED', getErrorMessage(err), { callerId: null }, ['Resolve the IDE session identity before running workflow commands.']);
+    }
+}
+export function deriveProjectRoot(options) {
+    return options.project ?? process.cwd();
+}
+/**
+ * The literal that means "no session could be resolved". Kept as a named
+ * constant because three call sites now have to ASK whether resolution
+ * failed rather than consume the value as if it were an id.
+ */
+export const UNKNOWN_SESSION_ID = 'unknown-sid';
+/**
+ * Resolve the session id for every `workflow *` command.
+ *
+ * Tier order (matches the idiom every other command family in this CLI
+ * already uses — see `job-commands.ts:85`, `container-commands.ts:138`):
+ *
+ *   1. `--session-id <sid>`             — explicit wins
+ *   2. `PEAKS_SESSION_ID` env var       — scripted / sub-process callers
+ *   3. `getCurrentSessionId(projectRoot)` — this caller's OWN binding
+ *      (`callers/<callerId>.json`) falling back to the project-global
+ *      `.peaks/_runtime/session.json`, the same resolver `peaks session
+ *      info --active` and `peaks session checkpoint` use
+ *   4. `unknown-sid`                    — nothing is bound
+ *
+ * Tier 3 was MISSING until 2026-09-15 (S6), and its absence is the whole
+ * defect: `workflow init` resolved on tiers 1–2 only, so with no flag and no
+ * env var it wrote the graph into `.peaks/_runtime/unknown-sid/graphs/`
+ * regardless of what the binding file said. `peaks workflow node prepare`
+ * then ran under the CORRECT session dir and reported `PEAKS_GRAPH_NOT_FOUND`
+ * — the graph it was asking for had been written one bucket over. The bucket
+ * accumulated artifacts from at least 4 distinct caller ids between 2026-09-01
+ * and 2026-09-15, i.e. it had never worked for anyone.
+ *
+ * The same prior-art sweep (`.peaks/memory/archived/2026-06-26-unknown-sid-root-cause.md`)
+ * converted six inline `?? 'unknown-sid'` sites to this 4-tier chain;
+ * `workflow-lifecycle-commands.ts` was missed. This is that site.
+ *
+ * The project root passed to tier 3 goes through the same `findProjectRoot`
+ * walk `session info` uses, so a command run from a SUBDIRECTORY of the
+ * project resolves the project's binding instead of `cwd`'s (which has none).
+ */
+export function deriveSessionId(options) {
+    if (typeof options.sessionId === 'string' && options.sessionId.length > 0)
+        return options.sessionId;
+    const fromEnv = process.env.PEAKS_SESSION_ID;
+    if (typeof fromEnv === 'string' && fromEnv.length > 0)
+        return fromEnv;
+    return (getCurrentSessionId(findProjectRoot(options.project ?? process.cwd()) ?? options.project ?? process.cwd()) ?? UNKNOWN_SESSION_ID);
+}

package/dist/cli/commands/workflow-commands.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The `peaks refactor | tech | workflow | route | autonomous | swarm | recommend`
+ * planning surface.
+ *
+ * This module is the registrar: each family owns its own file, and the two helpers
+ * they share live in `workflow-plan-helpers.ts`. The `peaks workflow` parent is
+ * created by the planning family and handed back, so the gate family attaches to
+ * the same group instead of creating a second one.
+ */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerWorkflowCommands(program: Command, io: ProgramIO): void;