@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.14010

package/dist/commands/session-hook.js

@@ -0,0 +1,97 @@
+/**
+ * The session commands as agent-tool hooks run them (TASK-562, WP-861).
+ *
+ * `--hook` (Codex, Cursor): the hook runner writes one JSON object on stdin naming the conversation
+ * (`session_id`). It is read once (lib/conversation.ts readHookConversationId), so two concurrent
+ * conversations of one tool get two sessions and one SessionEnd cannot close the other's.
+ * When no env channel carries that id into the agent's later shell commands, the start says which
+ * PB_CONVERSATION_ID to prefix. Cursor gets the same line in its context, plus the id as hook `env`
+ * output, which Cursor applies to its later hooks only.
+ *
+ * `--cursor`: a Cursor sessionStart hook reads one JSON object from stdout and adds its
+ * `additional_context` to the conversation, so the plain start text would never reach the agent.
+ * This runs the ordinary start, collects everything it prints (a refusal too, so the agent sees why
+ * no session opened) and prints it as that one object. `--cursor` reads the hook input as `--hook`.
+ * Claude Code's hooks need neither: its later shells carry CLAUDE_CODE_SESSION_ID.
+ */
+import { CLIError } from '../lib/errors.js';
+import { readHookConversationId, resolveConversationId, resolveEnvConversationId } from '../lib/conversation.js';
+import { runSessionClose, runSessionStart } from './session.js';
+/** The conversation id a later bare pb call would miss: read from the hook input, carried by no env channel. */
+function idToCarry() {
+    const id = resolveConversationId();
+    return id && id !== resolveEnvConversationId() ? id : null;
+}
+/** RULE-662: the one line that keeps a Codex or Cursor agent's later pb calls on this session. */
+export const carryLine = (id) => `Prefix PB_CONVERSATION_ID=${id} on every pb command in this session.`;
+/** `pb session start`: the ordinary start, with `--hook` reading the hook input, or with `--cursor` the JSON a Cursor hook reads. */
+export async function runSessionStartCommand({ cursor, hook, ...options }) {
+    if (cursor || hook)
+        readHookConversationId();
+    const carry = cursor || hook ? idToCarry() : null;
+    if (cursor)
+        return runSessionStartForCursor(options, carry);
+    await runSessionStart(options);
+    if (carry)
+        process.stdout.write(`${carryLine(carry)}\n`);
+}
+const HOOK_OPTION = 'Read the conversation from the hook input on stdin, as Codex and Cursor hooks pass it';
+/** Registers `pb session start` (moved here from index.ts so its options are one per line, TASK-562). */
+export function registerSessionStart(sessionCmd) {
+    sessionCmd
+        .command('start')
+        .description('Start a tracked write session')
+        .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+        .option('--cursor', 'Print the start as the JSON a Cursor sessionStart hook reads')
+        .option('--hook', HOOK_OPTION)
+        .option('--conversation <id>', 'Explicit conversation identity override — takes priority over env-detected channels. Pair with ' +
+        'PB_CONVERSATION_ID=<id> so later bare pb commands (orient, capture) attribute to the same conversation — ' +
+        'they resolve identity from env only')
+        .option('--role <entry-id>', 'Role to act as this session — only needed if you hold more than one; the error lists your roles if ' +
+        'omitted. Default: "role" in .productbrain/config.local.json')
+        .option('--team <entry-id>', 'Team the --role is held in — only needed if you hold that role in more than one team')
+        .option('--preview-method <method@version>', 'Serve a draft written in this workspace in place of that method\'s words, like direction@4')
+        .option('--preview-situation <facts>', 'Set the facts a method is picked from instead of reading them, comma-separated: rung=<purpose|vision|strategy|objective|key_result|none>, ' +
+        'firstEver, firstHere, toolFirst, creator (each =true or =false), rowsForPerson=<n>. A preview start writes no first-session fact')
+        .action(async (opts) => { await runSessionStartCommand(opts); });
+}
+/** Registers `pb session close` (moved here from index.ts, TASK-562). */
+export function registerSessionClose(sessionCmd) {
+    sessionCmd
+        .command('close')
+        .description('Close the active session (wrapup)')
+        .option('--force', 'Clear local session state even if server close fails')
+        .option('--hook', HOOK_OPTION)
+        .option('--conversation <id>', 'Close the session started with this --conversation <id>, so the next start on it resumes')
+        .action(async (opts) => { await runSessionCloseCommand(opts); });
+}
+/** `pb session close`: with `--hook`, the conversation is the one the hook input names. */
+export async function runSessionCloseCommand({ hook, ...options }) {
+    if (hook)
+        readHookConversationId();
+    await runSessionClose(options);
+}
+export async function runSessionStartForCursor(options = {}, carry = null) {
+    let text = '';
+    const collect = ((chunk) => { text += String(chunk); return true; });
+    const out = process.stdout.write.bind(process.stdout);
+    const err = process.stderr.write.bind(process.stderr);
+    process.stdout.write = collect;
+    process.stderr.write = collect;
+    try {
+        await runSessionStart(options);
+        // Cursor applies hook `env` to later hooks only, not to the agent's shell, so the agent reads the line as Codex does.
+        if (carry)
+            text += `${carryLine(carry)}\n`;
+    }
+    catch (e) {
+        const guidance = e instanceof CLIError && e.guidance ? `\n${e.guidance}` : '';
+        text += `\n${e instanceof Error ? e.message : String(e)}${guidance}`;
+    }
+    finally {
+        process.stdout.write = out;
+        process.stderr.write = err;
+    }
+    out(JSON.stringify({ additional_context: text.trim(), ...(carry ? { env: { PB_CONVERSATION_ID: carry } } : {}) }) + '\n');
+}
+//# sourceMappingURL=session-hook.js.map

package/dist/commands/session-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-hook.js","sourceRoot":"","sources":["../../src/commands/session-hook.ts"],"names":[],"mappings":"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"}

package/dist/commands/session-hook.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-hook.test.d.ts.map

package/dist/commands/session-hook.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-hook.test.d.ts","sourceRoot":"","sources":["../../src/commands/session-hook.test.ts"],"names":[],"mappings":""}

package/dist/commands/session-hook.test.js

@@ -0,0 +1,89 @@
+/**
+ * TASK-562: the session commands as hooks run them. `--cursor` prints one JSON object whose
+ * additional_context is everything the start printed, a refusal included; `--hook` and `--cursor`
+ * read the hook input; when no env channel carries that id, the start says which id to prefix
+ * (Cursor gets it as hook env output).
+ */
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+const { runSessionStart, runSessionClose, conv } = vi.hoisted(() => ({
+    runSessionStart: vi.fn(),
+    runSessionClose: vi.fn(),
+    conv: { hook: null, env: null, reads: 0 },
+}));
+vi.mock('./session.js', () => ({ runSessionStart: (o) => runSessionStart(o), runSessionClose: (o) => runSessionClose(o) }));
+vi.mock('../lib/conversation.js', () => ({
+    readHookConversationId: () => { conv.reads += 1; return conv.hook; },
+    resolveConversationId: () => conv.hook ?? conv.env,
+    resolveEnvConversationId: () => conv.env,
+}));
+import { CLIError } from '../lib/errors.js';
+import { carryLine, runSessionCloseCommand, runSessionStartCommand } from './session-hook.js';
+function capture() {
+    let out = '';
+    const spy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { out += String(chunk); return true; });
+    return { read: () => out, restore: () => spy.mockRestore() };
+}
+describe('session hooks', () => {
+    beforeEach(() => { conv.hook = null; conv.env = null; conv.reads = 0; });
+    afterEach(() => { runSessionStart.mockReset(); runSessionClose.mockReset(); vi.restoreAllMocks(); });
+    it('--cursor wraps what the start printed, stdout and stderr, as additional_context', async () => {
+        runSessionStart.mockImplementation(async () => {
+            process.stdout.write('Session started: abc\n');
+            process.stderr.write('One rule line\n');
+        });
+        const out = capture();
+        await runSessionStartCommand({ cursor: true, role: 'ROL-9' });
+        out.restore();
+        expect(runSessionStart).toHaveBeenCalledWith({ role: 'ROL-9' });
+        expect(JSON.parse(out.read())).toEqual({ additional_context: 'Session started: abc\nOne rule line' });
+    });
+    it('--cursor with a hook session_id no env channel carries tells the agent in the text and sets the hook env', async () => {
+        // Cursor applies hook env to later hooks only, not the agent's shell, so the sentence must reach the agent (Codex P1, round 3).
+        conv.hook = 'cursor-a';
+        runSessionStart.mockImplementation(async () => { process.stdout.write('Session started: abc\n'); });
+        const out = capture();
+        await runSessionStartCommand({ cursor: true });
+        out.restore();
+        expect(JSON.parse(out.read())).toEqual({
+            additional_context: `Session started: abc\n${carryLine('cursor-a')}`,
+            env: { PB_CONVERSATION_ID: 'cursor-a' },
+        });
+    });
+    it('a refused start reaches the agent with its next step, never a failed hook', async () => {
+        runSessionStart.mockRejectedValue(new CLIError('No API key configured.', { guidance: 'Run pb connect <token> in your project folder.' }));
+        const out = capture();
+        await runSessionStartCommand({ cursor: true });
+        out.restore();
+        expect(JSON.parse(out.read())).toEqual({ additional_context: 'No API key configured.\nRun pb connect <token> in your project folder.' });
+    });
+    it('--hook (Codex) reads the hook input and names the id to prefix, pinned word for word', async () => {
+        conv.hook = 'codex-a';
+        runSessionStart.mockResolvedValue(undefined);
+        const out = capture();
+        await runSessionStartCommand({ hook: true });
+        out.restore();
+        expect(conv.reads).toBe(1);
+        expect(out.read()).toBe(`${carryLine('codex-a')}\n`);
+        expect(carryLine('codex-a')).toBe('Prefix PB_CONVERSATION_ID=codex-a on every pb command in this session.');
+    });
+    it('--hook prints nothing extra when an env channel already carries the same id', async () => {
+        conv.hook = null;
+        conv.env = 'claude-a';
+        runSessionStart.mockResolvedValue(undefined);
+        const out = capture();
+        await runSessionStartCommand({ hook: true });
+        out.restore();
+        expect(out.read()).toBe('');
+    });
+    it('close --hook reads the hook input first; without a flag neither command reads stdin', async () => {
+        await runSessionCloseCommand({ hook: true, force: true });
+        expect(conv.reads).toBe(1);
+        expect(runSessionClose).toHaveBeenCalledWith({ force: true });
+        await runSessionCloseCommand({});
+        runSessionStart.mockResolvedValue(undefined);
+        await runSessionStartCommand({ conversation: 'c1' });
+        expect(conv.reads).toBe(1);
+        expect(runSessionStart).toHaveBeenCalledWith({ conversation: 'c1' });
+    });
+});
+//# sourceMappingURL=session-hook.test.js.map

package/dist/commands/session-hook.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-hook.test.js","sourceRoot":"","sources":["../../src/commands/session-hook.test.ts"],"names":[],"mappings":"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"}

package/dist/commands/session.d.ts

@@ -1,20 +1,77 @@
 /**
- * pb session start / close — CLI write session lifecycle.
- * Opens a tracked agent session (DEC-9, BR-8) with clientKind: 'cli' (DEC-184).
- * Session ID persisted to .productbrain/session.json (TEN-264 option 1).
- * BET-181 Slice 0: uses isJsonMode() for output branching. Existing --json flag
- * on session start preserved for backward compatibility.
+ * pb session start / close — CLI write session lifecycle. Opens a tracked agent session (DEC-9,
+ * BR-8) with clientKind: 'cli' (DEC-184). Session ID persisted to .productbrain/session.json
+ * (TEN-264 option 1). BET-181 Slice 0: uses isJsonMode() for output branching; existing --json
+ * flag on session start preserved for backward compatibility.
  */
-export declare function runSessionStart(options?: {
+type SessionStartOptions = {
     /** @deprecated Use global --json flag instead. Preserved for backward compatibility. */
     json?: boolean;
-}): Promise<void>;
+    /** WP-479 E2: explicit conversation-identity override (the manual seam — same tier as
+     *  PB_CONVERSATION_ID, takes priority over every env-detected channel). */
+    conversation?: string;
+    role?: string;
+    team?: string;
+    previewMethod?: string;
+    previewSituation?: string;
+};
+/**
+ * Auto-populate the session `label` (WP-479 E2, founder-day fix Pass 2) — the founder's recall
+ * cue for "which of my N conversations" is the worktree/branch, never a UUID. Priority:
+ * SUPERSET_WORKSPACE_NAME env → git branch (silent fail) → cwd basename. Server-side clamps to
+ * ~120 chars (mirrors MAX_TASK_LEN) — no client-side truncation needed here.
+ */
+export declare function resolveSessionLabel(): string;
+export declare function runSessionStart(options?: SessionStartOptions): Promise<void>;
 /**
  * pb session id — print current session ID bare to stdout (machine-readable).
  * Resolves TEN-707. Zero network call — reads local session.json only.
  */
 export declare function runSessionId(): void;
+/**
+ * pb session reset — hard-reset the worktree-local pb SESSION state. TEN-2189 / WP-456 E2.
+ *
+ * Discards session.json outright (via discardSession — NO resume marker, unlike
+ * `pb session close`). Purely local: no network call, no key needed — this is the recovery
+ * path when a session is stranded pinned to the wrong workspace (e.g. left over after a
+ * pb:preview/pb:real binding flip), so it must work even when the current binding is broken.
+ *
+ * Scope: SESSION state only. The preview *binding* (config.local.json keys + the
+ * .productbrain/PREVIEW_MODE marker) is owned end-to-end by `npm run pb:preview` /
+ * `npm run pb:real` — reset never touches it, so the marker can never disagree with the keys
+ * that actually route writes (codex PR #145 review: clearing the marker without the keys left
+ * the worktree silently still preview-bound). To return a preview-bound worktree to the real
+ * Chain: `pb session reset` (clear the session) then `npm run pb:real` (clear the binding).
+ *
+ * Guard (R4): if there IS an active session, confirm before discarding so in-flight captures
+ * aren't silently stranded. `--force` skips the prompt. In a non-interactive context the prompt
+ * can't run, so `--force` is required there.
+ *
+ * WP-479 review fix (Codex re-review): reset clears ALL session markers — the legacy session.json
+ * AND every per-conversation marker under `.productbrain/sessions/`. This is the recovery the
+ * pb:real/pb:preview binding-flip guard prints, and that guard refuses on ANY active marker; a
+ * conversation-scoped reset couldn't clear a sibling marker it has no env to resolve, so the flip
+ * would stay blocked unless `--force` (which strands the server session). A hard reset legitimately
+ * clears the whole worktree's local session state.
+ */
+export declare function runSessionReset(options?: {
+    force?: boolean;
+}): Promise<void>;
 export declare function runSessionClose(options?: {
     force?: boolean;
+    conversation?: string;
 }): Promise<void>;
+/**
+ * pb session list — active sessions (with the per-key quota gauge) + a handful of recent
+ * non-active ones. Pure read over `agent.listSessions`; no local session required — this is
+ * exactly the command you run when you're NOT sure which session is yours.
+ */
+export declare function runSessionList(): Promise<void>;
+/**
+ * pb session show <id-or-conversation> — reconstruct the full conversation lineage (all
+ * agentSessions rows across 2h resumes + legacy linkedPreviousSessionId chains) plus the
+ * governance serves recorded for the conversation.
+ */
+export declare function runSessionShow(idOrConversation: string): Promise<void>;
+export {};
 //# sourceMappingURL=session.d.ts.map

package/dist/commands/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/commands/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA0BH,wBAAsB,eAAe,CAAC,OAAO,GAAE;IAC7C,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAA;CACV,GAAG,OAAO,CAAC,IAAI,CAAC,CAsErB;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAOnC;AAED,wBAAsB,eAAe,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDtF"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/commands/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH,KAAK,mBAAmB,GAAG;IACzB,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;+EAC2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACnD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAU5C;AAwCD,wBAAsB,eAAe,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtF;AA4ND;;;GAGG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAUnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CtF;AAED,wBAAsB,eAAe,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiG7G;AAID;;;;GAIG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAOpD;AAWD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B5E"}