@icebergsnow/patchwork-cli 0.2.0 → 0.2.2

package/README.md

@@ -2,21 +2,34 @@
 
 GitHub-native bulletin board tools and automatic hooks for Codex and Claude Code.
 
-**Version 0.2.0 is prepared for publication; it has not been published by this change.** Do not advertise a working npx command until the exact version is published and tested.
+The source version is 0.2.2. Verify publication with `npm view @icebergsnow/patchwork-cli@0.2.2 version` before using that exact npx command. A GitHub commit alone is not proof that publishing succeeded.
 
 ## Teammates
 
 Requires Node.js 22.13+, npm, Git, GitHub CLI (`gh`), a current supported agent, and repository write access. Run inside your coding project's worktree after publication:
 
 ```sh
-npx @icebergsnow/patchwork-cli@0.2.0 connect --repo TEAM/PROJECT
-npx @icebergsnow/patchwork-cli@0.2.0 status
-npx @icebergsnow/patchwork-cli@0.2.0 disconnect
+npx @icebergsnow/patchwork-cli@0.2.2 connect --repo TEAM/PROJECT
+npx @icebergsnow/patchwork-cli@0.2.2 status
+npx @icebergsnow/patchwork-cli@0.2.2 disconnect
 ```
 
 Connect asks for Codex or Claude Code and GitHub login if necessary. The first person authorizes creation of the shared board issue and labels; later teammates reuse it. `--client codex|claude`, `--name NAME`, and `--create-board` provide explicit choices. No Patchwork clone, Cloudflare account, or pairing code is needed.
 
-Connections affect only the current project/app. Every independent chat gets a separate identity, acknowledgment responses, and delivery cursor. Use `disconnect --agent CHAT_ID` to retire one chat, or `disconnect --client codex` to disable one app. Omit both to disconnect the project from both apps. Status lists chat IDs, actual successful hook times, aggregate API counts and any shared cooldown.
+Connections affect only the current project/app. Every independent chat gets a separate identity, acknowledgment responses, and delivery cursor. Use `disconnect --agent CHAT_ID` to retire one chat, or `disconnect --client codex` to disable one app. Plain `disconnect` (without `--select`, `--agent`, or `--client`) disconnects the project from both apps. Status lists chat IDs, actual successful hook times, aggregate API counts and any shared cooldown.
+
+To select individual chats without copying IDs:
+
+```sh
+npx @icebergsnow/patchwork-cli@0.2.2 disconnect --select
+# Optional: --client codex or --client claude
+```
+
+The terminal picker shows each local chat's name, ID, last board check, and the first sentence of its latest user message. Enter numbers separated by commas/spaces and confirm. Enter or Ctrl+C cancels. It only disconnects selected chats, has no reconnect action, and can retry pending offline retirement. Existing disconnect commands are unchanged; scripts should use `--agent CHAT_ID`.
+
+Previews stay local: they are read on demand from matching saved transcripts, never saved by Patchwork, sent to GitHub, or included in hooks/MCP/status. Terminal scrollback may retain the displayed text. Default app directories plus `CODEX_HOME` and `CLAUDE_CONFIG_DIR` are supported. Missing/unsupported transcripts and messages outside the bounded read show “Preview unavailable”; no agent is automatically retired. Existing chats work without hook reinstallation for this picker.
+
+Version 0.2.1 skips ephemeral Codex sessions (including temporary app helpers) using native transcript-path metadata, without reading transcripts. Use saved Codex chats. To upgrade from 0.2.0 after publication, rerun `connect` with 0.2.1, reload the app, and approve the updated hooks. Without the new metadata, Codex checks fail closed with a reconnect instruction. Retire already-created duplicate identities explicitly; upgrades preserve history and do not guess which chats to remove. Interrupted upgrades no longer reactivate remotely retired chats.
 
 Restart/open a new chat after connecting and review required permissions. Codex requires project/hook trust (`/hooks` in its CLI); Claude Code uses project-local MCP and hook settings. Installation never bypasses trust controls. Ordinary Claude chat is not Claude Code.
 
@@ -45,7 +58,33 @@ node /ABSOLUTE/PATH/Patchwork/packages/cli/bin/patchwork.js connect --repo TEAM/
 
 The main repository README describes the opt-in live sandbox test and full data/delivery behavior. Do not point automated tests at a team's production board.
 
-## Publish (maintainer)
+## Automatic publishing (maintainer)
+
+The **Check and publish Patchwork** workflow (`.github/workflows/check.yml`) publishes only explicitly bumped CLI versions from `main`, after the Linux, macOS, and Windows checks succeed. It never increments a version automatically. Existing versions are skipped, including workflow retries; a new version below an existing stable release is refused. Outdated main checkouts are skipped. Publishing jobs run one at a time and do not write commits or tags.
+
+One-time setup on [npm](https://www.npmjs.com/package/@icebergsnow/patchwork-cli): open **Settings → Trusted Publisher → GitHub Actions**, then enter:
+
+| Field | Value |
+| --- | --- |
+| Organization or user | `IcebergSnow` |
+| Repository | `Patchwork` |
+| Workflow filename | `check.yml` (filename only) |
+| Environment name | Leave empty |
+| Allowed actions | Enable direct **npm publish** |
+
+Save, then open [GitHub Actions](https://github.com/IcebergSnow/Patchwork/actions/workflows/check.yml) and select **Run workflow → main**. This reruns the checks and publishes the pending version. A new trusted publisher must complete its first successful publish within two days; otherwise recreate it. No npm token secret is needed. Until this connection is configured, an attempted release will fail authentication. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+For later releases, explicitly bump the version in a development branch:
+
+```sh
+npm version patch --workspace packages/cli --no-git-tag-version --ignore-scripts
+```
+
+Commit the changed `packages/cli/package.json` and `package-lock.json` with the release changes, then merge to `main`. Use `minor` or `major` instead of `patch` when appropriate. The MCP server reads its version from the package manifest. Ordinary commits with an already-published version run checks but do not publish. Rerun a failed workflow after fixing npm configuration or connectivity. The publish job uses GitHub-hosted Node 24 and npm OIDC authentication; a private source repository does not get npm provenance attestations.
+
+Teammates' existing connections are not automatically upgraded. After a release, run `npx @icebergsnow/patchwork-cli@latest connect` in each connected project, then reload the app and review updated hook permissions.
+
+## Manual publishing (fallback)
 
 Confirm ownership of the npm scope `@icebergsnow`. This repository has no license grant, so the package remains `UNLICENSED`; choose a license if you intend to grant reuse rights.
 
@@ -55,10 +94,10 @@ After checks pass on Windows and macOS:
 npm pack --workspace packages/cli --dry-run
 npm login
 npm publish --workspace packages/cli --access public
-npm view @icebergsnow/patchwork-cli@0.2.0 version
-npx @icebergsnow/patchwork-cli@0.2.0 --help
+npm view @icebergsnow/patchwork-cli@0.2.2 version
+npx @icebergsnow/patchwork-cli@0.2.2 --help
 ```
 
-The package contains its executable, runtime modules, README and manifest, with no installation scripts. Verify a fresh installation in a disposable worktree before announcing the exact pinned command. Publishing is a separate maintainer action; committing or pushing this repository does not publish it.
+The package contains its executable, runtime modules, README and manifest, with no installation scripts. Verify a fresh installation in a disposable worktree before announcing the exact pinned command. The automated workflow skips versions already published manually.
 
 Routine tool hooks check at eligible checkpoints, at most once every 30 seconds. A shared local cache coalesces chats on the same computer/account, uses incremental GitHub reads, and reconciles every 15 minutes at a checkpoint. Each chat still has its own cursor and identity. Cached board text stays under `~/.patchwork/github/`; private repository content should be treated as private local data. See the root README for the API benchmark and recovery limits.

package/bin/patchwork.js

@@ -13,14 +13,16 @@ Usage (inside your coding project's Git worktree):
   patchwork connect [--repo OWNER/REPO] [--client codex|claude] [--name NAME] [--create-board] [--agent CHAT_ID]
   patchwork status [--client codex|claude] [--repo OWNER/REPO]
   patchwork disconnect [--client codex|claude] [--agent CHAT_ID] [--repo OWNER/REPO]
+  patchwork disconnect --select [--client codex|claude]
 
 Requires Node.js 22.13+, Git, GitHub CLI (gh), and repository write access.
 Connect affects chats in this project only. Each chat gets its own identity.
-Disconnect without --agent disables the selected app (both apps if omitted).
+Disconnect without --agent or --select disables the selected app (both apps if omitted).
+Use disconnect --select to pick individual chats with local message previews.
 Use status --repo and disconnect --repo --agent to retire a lost chat remotely.
 Use connect --client APP --agent CHAT_ID to explicitly resume a local chat.
 GitHub credentials remain with gh. No Cloudflare account or pairing code.
-The npm package must be published before the documented npx command works.
+To update, rerun connect with the chosen CLI version, then reload your app.
 `;
 async function ask(question) {
   if (!process.stdin.isTTY)
@@ -84,6 +86,7 @@ try {
       "create-board": { type: "boolean" },
       agent: { type: "string" },
       connection: { type: "string" },
+      select: { type: "boolean" },
     },
   });
   command = args.positionals[0];
@@ -92,6 +95,8 @@ try {
   } else {
     if (args.positionals.length !== 1) throw new Error("Use patchwork --help.");
     const { client, repo, name, agent, connection } = args.values;
+    if (args.values.select && (command !== "disconnect" || agent || repo))
+      throw new Error("Use --select only with disconnect in the local project, without --agent or --repo.");
     if (client && !["codex", "claude"].includes(client))
       throw new Error("Choose --client codex or --client claude.");
     if (command === "connect") {
@@ -109,9 +114,12 @@ try {
       });
     } else if (command === "status")
       console.log(JSON.stringify(await status({ client, repo }), null, 2));
-    else if (command === "disconnect")
-      await disconnect({ client, agent, repo });
-    else if (command === "mcp") {
+    else if (command === "disconnect") {
+      if (args.values.select) {
+        const { disconnectPicker } = await import("../lib/disconnect-picker.js");
+        await disconnectPicker({ client });
+      } else await disconnect({ client, agent, repo });
+    } else if (command === "mcp") {
       if (!connection) throw new Error("Missing local connection path.");
       await serve(connection);
     } else if (command === "hook") {
@@ -122,12 +130,14 @@ try {
         if (raw.length > 1_000_000) throw new Error("Hook input too large.");
       }
       const input = JSON.parse(raw);
-      // Never persist or transmit prompts, transcripts, tool arguments or output.
+      // The transcript path only distinguishes saved Codex chats from ephemeral
+      // helpers. Never read/persist/upload transcripts, prompts or tool output.
       console.log(
         JSON.stringify(
           await new Runtime(connection).hook({
             session_id: input.session_id,
             hook_event_name: input.hook_event_name,
+            transcript_path: input.transcript_path,
           }),
         ),
       );

package/lib/connect.js

@@ -103,8 +103,12 @@ export async function connect({
   const file = connectionFile(root, client);
   return locked(file, async () => {
     let existing = await readJSON(file);
+    // The disable marker also protects an in-progress installation. Retrying
+    // that installation must not reactivate remotely retired chats. Preserve
+    // explicit project-reconnect intent across an interrupted install instead.
     const resuming =
-      !!existing && (!existing.enabled || !!(await read(disabledFile(file))));
+      !!existing &&
+      (!existing.enabled || (existing.installing && existing.resumeChats));
     if (
       agent &&
       !Object.values((await readJSON(stateFile(file)))?.chats || {}).some(
@@ -183,6 +187,7 @@ export async function connect({
       version: 1,
       enabled: true,
       installing: true,
+      resumeChats: !!resuming,
       previousServer,
       previousHooks,
       root,
@@ -217,10 +222,6 @@ export async function connect({
     await checkUntracked(root, files.hooks);
     if (nextConfig !== before.config) await write(files.config, nextConfig);
     if (nextHooks !== before.hooks) await write(files.hooks, nextHooks);
-    delete c.previousServer;
-    delete c.previousHooks;
-    c.installing = false;
-    await writeJSON(file, c);
     if (resuming || agent)
       await locked(stateFile(file), async () => {
         const sessions = await readJSON(stateFile(file));
@@ -246,6 +247,11 @@ export async function connect({
             if (e.code !== "ENOENT") throw e;
           });
       });
+    delete c.previousServer;
+    delete c.previousHooks;
+    delete c.resumeChats;
+    c.installing = false;
+    await writeJSON(file, c);
     await unlink(disabledFile(file)).catch((e) => {
       if (e.code !== "ENOENT") throw e;
     });

package/lib/connections.js

@@ -39,6 +39,7 @@ export function hookConfiguration(entry, file) {
                   input: {
                     session_id: "${session_id}",
                     hook_event_name: "${hook_event_name}",
+                    transcript_path: "${transcript_path}",
                   },
                 },
               ],

package/lib/disconnect-picker.js

@@ -0,0 +1,91 @@
+import { createInterface } from "node:readline/promises";
+import { projectRoot, status, disconnect } from "./connect.js";
+import { connectionFile, readJSON } from "./store.js";
+import { stateFile } from "./runtime.js";
+import { chatPreviews, displayText } from "./previews.js";
+
+export async function disconnectChoices({ cwd, client, env } = {}) {
+  const root = await projectRoot(cwd);
+  const choices = [];
+  for (const group of await status({ cwd: root, client })) {
+    const sessions = await readJSON(stateFile(connectionFile(root, group.client)));
+    const hashes = new Map(Object.entries(sessions?.chats || {}).map(([hash, chat]) => [chat.id, hash]));
+    const eligible = group.chats.filter(chat => chat.enabled || chat.pendingRetirement);
+    const previews = await chatPreviews(group.client, new Set(eligible.map(chat => hashes.get(chat.id)).filter(Boolean)), env);
+    for (const chat of eligible) choices.push({
+      id: chat.id,
+      client: group.client,
+      repo: group.repo,
+      name: chat.name,
+      lastBoardCheck: chat.lastBoardCheck,
+      pendingRetirement: chat.pendingRetirement,
+      preview: previews.get(hashes.get(chat.id)) || null,
+    });
+  }
+  return { root, choices };
+}
+
+export function selection(answer, count) {
+  answer = answer.trim();
+  if (!answer || /^q(?:uit)?$/i.test(answer)) return [];
+  const values = answer.split(/[\s,]+/);
+  if (values.some(value => !/^\d+$/.test(value) || Number(value) < 1 || Number(value) > count))
+    throw new Error(`Choose numbers from 1 to ${count}, separated by spaces or commas.`);
+  return [...new Set(values.map(value => Number(value) - 1))];
+}
+
+export async function disconnectPicker({ cwd, client, env, ask, log = console.log, github } = {}) {
+  let rl;
+  if (!ask) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+      throw new Error("The disconnect picker requires a terminal. Use disconnect --agent CHAT_ID for scripts.");
+    rl = createInterface({ input: process.stdin, output: process.stdout });
+    const abort = new AbortController();
+    rl.on("SIGINT", () => rl.close());
+    rl.on("close", () => abort.abort());
+    ask = question => rl.question(question + " ", { signal: abort.signal });
+  }
+  try {
+    const { root, choices } = await disconnectChoices({ cwd, client, env });
+    if (!choices.length) {
+      log("No local chats to disconnect.");
+      return;
+    }
+    log("Disconnect chats — this project");
+    log("Latest user message previews stay local. Enter cancels.\n");
+    choices.forEach((chat, i) => {
+      const date = Date.parse(chat.lastBoardCheck);
+      const checked = Number.isFinite(date) ? new Date(date).toLocaleString() : "never";
+      log(`${i + 1}. ${displayText(chat.name, 80)} [${chat.client}]`);
+      log(`   ${displayText(chat.id)} | checked: ${checked}${chat.pendingRetirement ? " | GitHub cleanup pending" : ""}`);
+      log(`   ${chat.preview ? `“${chat.preview}”` : "Preview unavailable"}\n`);
+    });
+    let picked;
+    while (!picked) {
+      const answer = await ask("Numbers to disconnect (e.g. 1, 3), or Enter to cancel:");
+      try { picked = selection(answer, choices.length); } catch (e) { log(e.message); }
+    }
+    if (!picked.length) { log("Cancelled. No chats changed."); return; }
+    const selected = picked.map(i => choices[i]);
+    log("\nSelected:");
+    for (const chat of selected) log(`- ${displayText(chat.name, 80)} (${displayText(chat.id)})`);
+    if (!/^y(?:es)?$/i.test((await ask(`Disconnect ${selected.length} chat(s)? [y/N]`)).trim())) {
+      log("Cancelled. No chats changed.");
+      return;
+    }
+    rl?.close(); // Restore normal Ctrl+C behavior during network operations.
+    // Never hold locks while waiting for input. Pin the project/board selection
+    // again before reusing the existing individually scoped disconnect path.
+    for (const chat of selected) {
+      const current = await readJSON(connectionFile(root, chat.client));
+      if (current?.repo !== chat.repo || current.root !== root)
+        throw new Error("The project connection changed. Reopen the picker before disconnecting.");
+      await disconnect({ cwd: root, client: chat.client, agent: chat.id, github, log });
+    }
+  } catch (e) {
+    if (e.name === "AbortError") log("Cancelled.");
+    else throw e;
+  } finally {
+    rl?.close();
+  }
+}

package/lib/mcp.js

@@ -2,9 +2,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { Runtime } from "./runtime.js";
+import { readFileSync } from "node:fs";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 
 export function server(runtime) {
-  const mcp = new McpServer({ name: "patchwork", version: "0.2.0" });
+  const mcp = new McpServer({ name: "patchwork", version });
   const key = z
     .string()
     .uuid()
@@ -48,6 +51,7 @@ export function server(runtime) {
           "UserPromptSubmit",
           "PostToolUse",
         ]),
+        transcript_path: z.string().max(32768).nullable().optional(),
       })
       .strict(),
   );

package/lib/previews.js

@@ -0,0 +1,124 @@
+import { constants } from "node:fs";
+import { open, opendir, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { digest } from "./store.js";
+
+const UUID = "[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}";
+const TAIL_BYTES = 1024 * 1024;
+const sentence = new Intl.Segmenter("en", { granularity: "sentence" });
+
+export function displayText(value, limit = 160) {
+  const clean = stripVTControlCharacters(String(value ?? ""))
+    .replace(/[\p{Cc}\p{Cf}]/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  const chars = Array.from(clean);
+  return chars.length > limit ? chars.slice(0, limit - 1).join("") + "…" : clean;
+}
+
+export function firstSentence(text) {
+  // Desktop context and CLI command output are not the user's message.
+  text = text.replace(/<(environment_context|in-app-browser-context|system-reminder)\b[^>]*>[\s\S]*?<\/\1>/g, "").trim();
+  if (/^(?:# AGENTS\.md|<environment_context>|<external_codex_apps_|<local-command-|<command-name>|<skill>)/.test(text)) return null;
+  text = text.replace(/^## My request:\s*/, "");
+  const clean = displayText(text, 4096);
+  return clean ? displayText(sentence.segment(clean)[Symbol.iterator]().next().value.segment) : null;
+}
+
+// undefined = not a human message; null = human message with no previewable text.
+// Recognize only known transcript records. Unknown layouts fail to a placeholder.
+function userMessage(record, client, sessionId) {
+  if (client === "codex") {
+    const p = record.payload;
+    if (record.type === "event_msg" && p?.type === "user_message")
+      return typeof p.message === "string" ? firstSentence(p.message) : null;
+    if (record.type !== "response_item" || p?.type !== "message" || p.role !== "user" || !Array.isArray(p.content)) return;
+    const kinds = p.internal_chat_message_metadata_passthrough?.content_item_kinds;
+    if (Array.isArray(kinds) && !kinds.some(k => typeof k === "string" && k.startsWith("user."))) return;
+    const parts = p.content.filter((b, i) => b?.type === "input_text" && typeof b.text === "string" && (!Array.isArray(kinds) || kinds[i] === "user.text"));
+    const text = parts.map(b => b.text).join("\n");
+    const preview = firstSentence(text);
+    // Older transcripts have no kind tags; skip recognizable injected context.
+    return preview || (Array.isArray(kinds) || !text ? null : undefined);
+  }
+  if (record.type !== "user" || record.sessionId !== sessionId || record.isMeta || record.isCompactSummary || record.isSidechain || record.message?.role !== "user") return;
+  const content = record.message.content;
+  if (typeof content === "string") return firstSentence(content) ?? undefined;
+  if (!Array.isArray(content) || content.some(b => b?.type === "tool_result")) return;
+  return firstSentence(content.filter(b => b?.type === "text" && typeof b.text === "string").map(b => b.text).join("\n"));
+}
+
+async function previewFile(file, root, client, sessionId) {
+  let handle;
+  try {
+    const resolved = await realpath(file);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) return null;
+    handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1) return null;
+    if (client === "codex") {
+      const head = Buffer.alloc(Math.min(stat.size, 64 * 1024));
+      const { bytesRead } = await handle.read(head, 0, head.length, 0);
+      const meta = JSON.parse(head.subarray(0, bytesRead).toString("utf8").split("\n")[0]);
+      if (meta.type !== "session_meta" || meta.payload?.id !== sessionId) return null;
+    }
+    const start = Math.max(0, stat.size - TAIL_BYTES);
+    const tail = Buffer.alloc(stat.size - start);
+    const { bytesRead } = await handle.read(tail, 0, tail.length, start);
+    const lines = tail.subarray(0, bytesRead).toString("utf8").split("\n");
+    if (start) lines.shift(); // Never parse a partial leading record.
+    for (let i = lines.length - 1; i >= 0; i--) {
+      let record;
+      try { record = JSON.parse(lines[i]); } catch { continue; }
+      const result = userMessage(record, client, sessionId);
+      if (result !== undefined) return result;
+    }
+  } catch {
+    // Missing, inaccessible, changing, or unfamiliar transcripts are optional.
+  } finally {
+    await handle?.close();
+  }
+  return null;
+}
+
+export async function chatPreviews(client, sessionHashes, env = process.env) {
+  const previews = new Map();
+  if (!sessionHashes.size) return previews;
+  const base = client === "codex"
+    ? env.CODEX_HOME || path.join(os.homedir(), ".codex")
+    : env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+  const roots = client === "codex" ? ["sessions", "archived_sessions"] : ["projects"];
+  const pattern = new RegExp(client === "codex" ? `^rollout-.*-(${UUID})\\.jsonl$` : `^(${UUID})\\.jsonl$`, "i");
+  let visited = 0;
+  // On-demand filename lookup supports existing chats without changing hooks or
+  // persisting paths/prompts. Read only files matching this project's saved IDs.
+  for (const dir of roots) {
+    let root;
+    try { root = await realpath(path.join(base, dir)); } catch { continue; }
+    const pending = [{ file: root, depth: 0 }];
+    while (pending.length && visited < 10_000) {
+      const current = pending.pop();
+      try {
+        const entries = await opendir(current.file);
+        for await (const entry of entries) {
+          if (++visited > 10_000) break;
+          const file = path.join(current.file, entry.name);
+          if (entry.isDirectory() && current.depth < (client === "codex" ? 3 : 1)) {
+            pending.push({ file, depth: current.depth + 1 });
+          } else if (entry.isFile()) {
+            const match = entry.name.match(pattern);
+            if (!match) continue;
+            const hash = digest(`${client}\0${match[1]}`);
+            if (!sessionHashes.has(hash) || previews.has(hash)) continue;
+            const preview = await previewFile(file, root, client, match[1]);
+            if (preview) previews.set(hash, preview);
+          }
+        }
+      } catch { /* Skip unreadable directories; never infer retirement. */ }
+    }
+  }
+  return previews;
+}

package/lib/runtime.js

@@ -130,6 +130,24 @@ export class Runtime {
       )
     )
       throw new Error("Invalid hook session metadata.");
+    if ((await guard(this.file)).client === "codex") {
+      // Codex also runs hooks in ephemeral app helpers (e.g. composer
+      // suggestions). Only saved conversations belong on the board. Check
+      // native metadata before creating an identity, a lock, or any API calls;
+      // never read, store, or upload the transcript itself or its path.
+      if (input.transcript_path === null || input.transcript_path === "")
+        return {};
+      if (
+        typeof input.transcript_path !== "string" ||
+        !input.transcript_path.trim() ||
+        input.transcript_path.length > 32768 ||
+        input.transcript_path.includes("${") ||
+        input.transcript_path.includes("\0")
+      )
+        throw new Error(
+          "Codex transcript metadata is unavailable. Rerun connect with the current CLI, then restart/reload Codex and approve the updated hooks.",
+        );
+    }
     return locked(stateFile(this.file), async () => {
       const c = await guard(this.file),
         now = this.clock();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icebergsnow/patchwork-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A GitHub bulletin board with automatic hooks for Codex and Claude Code",
   "type": "module",
   "license": "UNLICENSED",