@brainervirus/workit-core 8.1.0 → 8.3.0

package/src/hooks/shell-words.ts

@@ -0,0 +1,128 @@
+// A small shell tokenizer shared by the hooks: quoted words, operators,
+// redirects, heredoc bodies and `( … )` group markers. Pure string parsing,
+// no I/O. Two dialects:
+//   - posix (Bash, sh, zsh): `\` escapes, '…' is literal, "…" honors `\"`;
+//   - powershell (Claude Code's PowerShell tool): `\` is a path separator,
+//     the backtick escapes, '…' is literal with '' for a quote, "…" honors `".
+export type Segment = {
+  words: string[];
+  redirects: string[];
+  /** A `(`/`$(` group starts or ends here; the segment carries no words. */
+  group?: "open" | "close";
+};
+
+export type ShellDialect = "posix" | "powershell";
+
+/** The index of the quote closing the one at `start`, or -1. */
+const closingQuote = (command: string, start: number, dialect: ShellDialect): number => {
+  const quote = command[start];
+  for (let index = start + 1; index < command.length; index++) {
+    const char = command[index];
+    if (quote === "'") {
+      if (char !== "'") continue;
+      // PowerShell: '' inside single quotes is one quote.
+      if (dialect === "powershell" && command[index + 1] === "'") {
+        index++;
+        continue;
+      }
+      return index;
+    }
+    if ((dialect === "posix" && char === "\\") || (dialect === "powershell" && char === "`")) {
+      index++;
+      continue;
+    }
+    if (char === '"') return index;
+  }
+  return -1;
+};
+
+/** The text of a quoted span without its quotes, escapes resolved. */
+const unquote = (body: string, quote: string, dialect: ShellDialect): string => {
+  if (quote === "'") return dialect === "powershell" ? body.replaceAll("''", "'") : body;
+  return dialect === "posix" ? body.replace(/\\(["\\$`])/g, "$1") : body.replace(/`(.)/g, "$1");
+};
+
+/** Tokenize `command` into simple-command segments. */
+export const segmentsOf = (command: string, dialect: ShellDialect = "posix"): Segment[] => {
+  const segments: Segment[] = [];
+  let current: Segment = { words: [], redirects: [] };
+  let word = "";
+  let inWord = false;
+  let pending: "redirect" | "input" | "heredoc" | null = null;
+  const heredocs: string[] = [];
+  const escape = dialect === "posix" ? "\\" : "`";
+  const flushWord = () => {
+    if (!inWord) return;
+    if (pending === "redirect") {
+      if (!word.startsWith("&")) current.redirects.push(word);
+    } else if (pending === "heredoc") heredocs.push(word.replace(/^-/, ""));
+    else if (pending !== "input") current.words.push(word);
+    pending = null;
+    word = "";
+    inWord = false;
+  };
+  const flushSegment = () => {
+    flushWord();
+    if (current.words.length || current.redirects.length) segments.push(current);
+    current = { words: [], redirects: [] };
+  };
+  for (let index = 0; index < command.length; index++) {
+    const char = command[index];
+    if (char === "'" || char === '"') {
+      const end = closingQuote(command, index, dialect);
+      word += unquote(command.slice(index + 1, end < 0 ? undefined : end), char, dialect);
+      inWord = true;
+      index = end < 0 ? command.length : end;
+    } else if (char === escape && index + 1 < command.length) {
+      word += command[++index];
+      inWord = true;
+    } else if (char === "\n") {
+      flushSegment();
+      // Skip heredoc bodies up to each delimiter line.
+      while (heredocs.length) {
+        const delimiter = heredocs.shift()!;
+        const lines = command.slice(index + 1).split("\n");
+        const at = lines.findIndex((line) => line.trim() === delimiter);
+        const skipped = (at < 0 ? lines : lines.slice(0, at + 1)).join("\n").length + 1;
+        index += skipped;
+      }
+    } else if (/\s/.test(char)) flushWord();
+    else if (char === "(" || char === ")") {
+      // `$(` opens a command substitution: the `$` is not a word.
+      if (char === "(" && inWord && word.endsWith("$")) {
+        word = word.slice(0, -1);
+        inWord = word !== "";
+      }
+      flushSegment();
+      segments.push({ words: [], redirects: [], group: char === "(" ? "open" : "close" });
+    } else if (";&|".includes(char)) {
+      if (char === "&" && command[index + 1] === ">") continue;
+      flushSegment();
+    } else if (char === ">") {
+      // `2>`, `&>`: the fd digit is not a word.
+      if (inWord && /^\d$/.test(word)) {
+        word = "";
+        inWord = false;
+      } else flushWord();
+      if (command[index + 1] === ">") index++;
+      if (command[index + 1] === "&") {
+        index++;
+        word = "&";
+        inWord = true;
+      }
+      pending = "redirect";
+    } else if (char === "<" && dialect === "posix") {
+      flushWord();
+      if (command[index + 1] === "<") {
+        index++;
+        if (command[index + 1] === "<") index++;
+        pending = "heredoc";
+      } else pending = "input";
+    } else {
+      word += char;
+      inWord = true;
+    }
+  }
+  flushSegment();
+  return segments;
+};

package/src/hooks/write-gate.ts

@@ -11,6 +11,7 @@ import { latestJudgment, writeBlockers, type WriteBlocker } from "../core/policy
 import { applicableDecision } from "../core/task-evaluation";
 import { ledgerPath } from "../ledger";
 import type { HookDecision } from "./protocol";
+import { segmentsOf } from "./shell-words";
 
 const NONE: HookDecision = { kind: "none" };
 
@@ -51,84 +52,6 @@ const exempt = (cwd: string, root: string, file: string, plans: ReadonlySet<stri
   );
 };
 
-type Segment = { words: string[]; redirects: string[] };
-
-/** A small shell tokenizer: quoted words, operators, redirects and heredoc bodies. */
-const segmentsOf = (command: string): Segment[] => {
-  const segments: Segment[] = [];
-  let current: Segment = { words: [], redirects: [] };
-  let word = "";
-  let inWord = false;
-  let pending: "redirect" | "input" | "heredoc" | null = null;
-  const heredocs: string[] = [];
-  const flushWord = () => {
-    if (!inWord) return;
-    if (pending === "redirect") {
-      if (!word.startsWith("&")) current.redirects.push(word);
-    } else if (pending === "heredoc") heredocs.push(word.replace(/^-/, ""));
-    else if (pending !== "input") current.words.push(word);
-    pending = null;
-    word = "";
-    inWord = false;
-  };
-  const flushSegment = () => {
-    flushWord();
-    if (current.words.length || current.redirects.length) segments.push(current);
-    current = { words: [], redirects: [] };
-  };
-  for (let index = 0; index < command.length; index++) {
-    const char = command[index];
-    if (char === "'" || char === '"') {
-      const end = command.indexOf(char, index + 1);
-      word += command.slice(index + 1, end < 0 ? undefined : end);
-      inWord = true;
-      index = end < 0 ? command.length : end;
-    } else if (char === "\\" && index + 1 < command.length) {
-      word += command[++index];
-      inWord = true;
-    } else if (char === "\n") {
-      flushSegment();
-      // Skip heredoc bodies up to each delimiter line.
-      while (heredocs.length) {
-        const delimiter = heredocs.shift()!;
-        const lines = command.slice(index + 1).split("\n");
-        const at = lines.findIndex((line) => line.trim() === delimiter);
-        const skipped = (at < 0 ? lines : lines.slice(0, at + 1)).join("\n").length + 1;
-        index += skipped;
-      }
-    } else if (/\s/.test(char)) flushWord();
-    else if (";&|()".includes(char)) {
-      if (char === "&" && command[index + 1] === ">") continue;
-      flushSegment();
-    } else if (char === ">") {
-      // `2>`, `&>`: the fd digit is not a word.
-      if (inWord && /^\d$/.test(word)) {
-        word = "";
-        inWord = false;
-      } else flushWord();
-      if (command[index + 1] === ">") index++;
-      if (command[index + 1] === "&") {
-        index++;
-        word = "&";
-        inWord = true;
-      }
-      pending = "redirect";
-    } else if (char === "<") {
-      flushWord();
-      if (command[index + 1] === "<") {
-        index++;
-        if (command[index + 1] === "<") index++;
-        pending = "heredoc";
-      } else pending = "input";
-    } else {
-      word += char;
-      inWord = true;
-    }
-  }
-  flushSegment();
-  return segments;
-};
-
 const PREFIXES = new Set(["sudo", "command", "env", "nohup", "time", "exec", "xargs"]);
 const operands = (words: string[]) => words.filter((item) => !item.startsWith("-"));
 

package/src/host-session.ts

@@ -0,0 +1,53 @@
+// The acting host session for a `workit` call made from an agent's shell.
+// WORKIT_SESSION_ID, when set, wins (Claude Code exports it from SessionStart; a lead
+// assigns one to a verifier), unless WORKIT_HOST shows it came from another host. Otherwise the id each host itself puts in its
+// shell tool's environment is used, so commits and verdicts made on those
+// hosts carry the same session id their hooks see (M5):
+//   - OpenCode V2: OPENCODE_SESSION_ID (the shell tool's session id);
+//   - Pi: PI_SESSION_ID (the bash tool exposes the Pi session id);
+//   - Codex CLI and Desktop: CODEX_THREAD_ID (the thread id hooks get as session_id).
+// Cursor puts no conversation id in its shell; its hook names the id to use.
+
+export type HostSession = { host: string | null; session: string | null };
+
+const HOST_SESSION_VARS: ReadonlyArray<readonly [string, (env: NodeJS.ProcessEnv) => string]> = [
+  ["OPENCODE_SESSION_ID", () => "opencode"],
+  ["PI_SESSION_ID", () => "pi"],
+  [
+    "CODEX_THREAD_ID",
+    (env) =>
+      env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE === "Codex Desktop" ||
+      env.CODEX_ELECTRON_RESOURCES_PATH
+        ? "codex_desktop"
+        : "codex_cli",
+  ],
+];
+
+const family = (host: string | null): string | null =>
+  host?.replace(/_(?:cli|desktop)$/, "") ?? null;
+
+/**
+ * WORKIT_HOST/WORKIT_SESSION_ID, else the host's own shell session variable.
+ * A WORKIT_SESSION_ID whose WORKIT_HOST names another host was inherited from
+ * an outer session (Codex started from Claude Code's Bash): the inner host's
+ * own id wins, so the CLI acts as the session that host's hooks see.
+ */
+export function hostSessionFromEnv(env: NodeJS.ProcessEnv): HostSession {
+  const value = (key: string): string | null => env[key]?.trim() || null;
+  let inner: HostSession | null = null;
+  for (const [key, host] of HOST_SESSION_VARS) {
+    const session = value(key);
+    if (session) {
+      inner = { host: host(env), session };
+      break;
+    }
+  }
+  const declared = value("WORKIT_HOST");
+  // Set, even empty, it is the answer: `WORKIT_SESSION_ID=` opts out of the fallback.
+  if (env.WORKIT_SESSION_ID !== undefined) {
+    const inherited =
+      inner !== null && declared !== null && family(declared) !== family(inner.host);
+    if (!inherited) return { host: declared, session: value("WORKIT_SESSION_ID") };
+  }
+  return inner ? { host: inner.host, session: inner.session } : { host: declared, session: null };
+}

package/src/ledger.ts

@@ -40,6 +40,7 @@ import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { GIT_TIMEOUTS, currentBranch, headSha, patchId, worktreeTree } from "./git/rev";
+import { hostSessionFromEnv } from "./host-session";
 import { resolveStore } from "./store/paths";
 
 export const LEDGER_VERSION = 1;
@@ -304,15 +305,16 @@ export function ledgerPath(cwd: string): LedgerResult<string> {
 // ---------------------------------------------------------------------------
 // append
 
-/** The acting identity from the environment. */
+/** The acting identity from the environment (host-session.ts: WORKIT_SESSION_ID, else the host's own shell session id). */
 export function actorFromEnv(env: NodeJS.ProcessEnv): LedgerActor {
   const value = (key: string): string | null => {
     const raw = env[key]?.trim();
     return raw ? raw : null;
   };
+  const acting = hostSessionFromEnv(env);
   return {
-    host: value("WORKIT_HOST") ?? "cli",
-    session: value("WORKIT_SESSION_ID"),
+    host: acting.host ?? "cli",
+    session: acting.session,
     agentId: value("WORKIT_AGENT_ID"),
   };
 }
@@ -551,6 +553,18 @@ export function appendObserved(
   return appendRaw(cwd, { ...row, observer: "workit_cli" }, options);
 }
 
+/**
+ * A row a host hook observed (a raw shell `git commit`), stamped
+ * `observer:"host_hook"`: weaker than the CLI's own observation, but enough
+ * to name the session that authored a commit (D18 honest-agent model).
+ */
+export function appendHookObserved(
+  cwd: string,
+  row: Record<string, unknown> & { type: string; actor: LedgerActor },
+): LedgerResult<Record<string, unknown>> {
+  return appendRaw(cwd, { ...row, observer: "host_hook" }, {});
+}
+
 // ---------------------------------------------------------------------------
 // read (D17: tolerant)