inject-steer 0.0.0-stage → 0.1.0

package/src/adapters/claude-code/install.js

@@ -0,0 +1,211 @@
+// Registers inject's hooks in Claude Code's user settings
+// (~/.claude/settings.json, or $CLAUDE_CONFIG_DIR/settings.json).
+//
+// The tool hooks are shell one-liners that exit immediately unless the wrapper
+// has a message of the right kind queued, so Claude sessions started without
+// `inject`, and tool calls with nothing queued, never start Node.
+//
+// The UserPromptSubmit hook runs in every session (once per prompt you send)
+// to log messages typed into Claude Code's own queue mid-turn.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const MARKER = '# inject-hook';
+const HOOK_JS = fileURLToPath(new URL('./hook.js', import.meta.url));
+const PROMPT_HOOK_JS = fileURLToPath(new URL('./prompt-hook.js', import.meta.url));
+
+export function settingsPath() {
+  const base = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  return path.join(base, 'settings.json');
+}
+
+function shellQuote(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+export function hookCommand(event, flag, nodePath = process.execPath) {
+  if (flag === 'normal') return normalHookCommand(event, nodePath);
+  return `[ -e "$INJECT_DIR/${flag}" ] || exit 0; exec "$INJECT_NODE" ${shellQuote(HOOK_JS)} ${event} ${MARKER}`;
+}
+
+// Tool-boundary delivery of normal notes. Under the wrapper ($INJECT_DIR set)
+// it checks the wrapper's flag file. In a plain `claude` session it checks for
+// a pending file from the /inject mod (src/adapters/claude-code/plain.js,
+// pendingDir()). Either way it stays in the shell unless there is something
+// to deliver.
+function normalHookCommand(event, nodePath) {
+  return [
+    'if [ -n "$INJECT_DIR" ]; then [ -e "$INJECT_DIR/normal" ] || exit 0;',
+    'else set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/inject-pending/*.jsonl; [ -e "$1" ] || exit 0; fi;',
+    `N="\${INJECT_NODE:-${nodePath.replace(/[\\"$`]/g, '\\$&')}}"; [ -x "$N" ] || N=node;`,
+    `exec "$N" ${shellQuote(HOOK_JS)} ${event} ${MARKER}`,
+  ].join(' ');
+}
+
+// Plain `claude` sessions don't have $INJECT_NODE, and a GUI-launched session
+// may not have Node on PATH, so prefer the Node that ran the install.
+export function promptHookCommand(nodePath = process.execPath) {
+  return `N=${shellQuote(nodePath)}; [ -x "$N" ] || N=node; exec "$N" ${shellQuote(PROMPT_HOOK_JS)} ${MARKER}`;
+}
+
+function hooks() {
+  return [
+    { event: 'PreToolUse', command: hookCommand('PreToolUse', 'urgent'), timeout: 10 },
+    { event: 'PostToolUse', command: hookCommand('PostToolUse', 'normal'), timeout: 10 },
+    { event: 'PostToolUseFailure', command: hookCommand('PostToolUseFailure', 'normal'), timeout: 10 },
+    { event: 'UserPromptSubmit', command: promptHookCommand(), timeout: 5 },
+  ];
+}
+
+function isOurs(handler) {
+  return typeof handler?.command === 'string' && handler.command.includes(MARKER);
+}
+
+function readSettings(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw err;
+  }
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${file} is not valid JSON (${err.message}). Fix it, then run inject --install again.`);
+  }
+}
+
+function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.inject-backup`);
+  const tmp = `${file}.inject-tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+  fs.renameSync(tmp, file);
+}
+
+/** Removes our handlers; returns true if anything was removed. */
+function strip(settings) {
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== 'object') return false;
+  let removed = false;
+  for (const event of Object.keys(hooks)) {
+    if (!Array.isArray(hooks[event])) continue;
+    hooks[event] = hooks[event]
+      .map((group) => {
+        if (!Array.isArray(group?.hooks)) return group;
+        const kept = group.hooks.filter((h) => !isOurs(h));
+        if (kept.length !== group.hooks.length) removed = true;
+        return { ...group, hooks: kept };
+      })
+      .filter((group) => !Array.isArray(group?.hooks) || group.hooks.length > 0);
+    if (hooks[event].length === 0) delete hooks[event];
+  }
+  if (Object.keys(hooks).length === 0) delete settings.hooks;
+  return removed;
+}
+
+function countOurs(settings) {
+  let n = 0;
+  for (const groups of Object.values(settings.hooks || {})) {
+    for (const g of Array.isArray(groups) ? groups : []) n += (g?.hooks || []).filter(isOurs).length;
+  }
+  return n;
+}
+
+export function install() {
+  const file = settingsPath();
+  const settings = readSettings(file);
+  // Already exactly what we'd write: leave the file (and its key order) alone.
+  const wanted = hooks();
+  const present = (settings.hooks && wanted.every(({ event, command }) => (settings.hooks[event] || []).some((g) => (g.hooks || []).some((h) => h.command === command)))) || false;
+  if (present && countOurs(settings) === wanted.length) return { path: file, changed: false };
+  const before = JSON.stringify(settings);
+  strip(settings);
+  settings.hooks ??= {};
+  for (const { event, command, timeout } of hooks()) {
+    settings.hooks[event] ??= [];
+    settings.hooks[event].push({ hooks: [{ type: 'command', command, timeout }] });
+  }
+  const changed = JSON.stringify(settings) !== before;
+  if (changed) writeSettings(file, settings);
+  return { path: file, changed };
+}
+
+export function uninstall() {
+  const file = settingsPath();
+  const settings = readSettings(file);
+  const changed = strip(settings);
+  if (changed) writeSettings(file, settings);
+  return { path: file, changed };
+}
+
+export function isInstalled() {
+  try {
+    const installed = readSettings(settingsPath()).hooks || {};
+    return hooks().every(({ event, command }) =>
+      (installed[event] || []).some((g) => (g.hooks || []).some((h) => h.command === command)),
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The /inject command for plain `claude` sessions is a mod (mod/), which Claude
+// Code loads as a plugin. This repo is also a one-plugin marketplace, so
+// installing it is two `claude plugin` commands. A directory marketplace loads
+// in place, so edits under mod/ apply at the next session start.
+
+const PLUGIN = 'inject@inject';
+const PACKAGE_ROOT = fileURLToPath(new URL('../../../', import.meta.url));
+
+function claude(args) {
+  const bin = process.env.INJECT_COMMAND || 'claude';
+  const env = { ...process.env };
+  delete env.CLAUDE_CODE_CHILD_SESSION;
+  const r = spawnSync(bin, ['plugin', ...args], { encoding: 'utf8', timeout: 60_000, env });
+  return { ok: r.status === 0, missing: r.error?.code === 'ENOENT', out: `${r.stdout || ''}${r.stderr || ''}`.trim() };
+}
+
+const manual = (cmds) => cmds.map((c) => `    claude plugin ${c}`).join('\n');
+
+/** @returns {{ok:boolean, message:string}} */
+export function installMod() {
+  const steps = [['marketplace', 'add', PACKAGE_ROOT], ['install', PLUGIN]];
+  for (const args of steps) {
+    const r = claude(args);
+    if (!r.ok) {
+      const why = r.missing ? "couldn't find the `claude` command on your PATH" : r.out.split('\n').pop();
+      return {
+        ok: false,
+        message: `could not install the /inject command for plain claude (${why}). Run these yourself:\n${manual(steps.map((a) => a.map((x) => (x === PACKAGE_ROOT ? `"${PACKAGE_ROOT}"` : x)).join(' ')))}`,
+      };
+    }
+  }
+  return { ok: true, message: `/inject command installed for plain claude (plugin ${PLUGIN}). Start a new claude session to use it.` };
+}
+
+/** @returns {{ok:boolean, message:string}} */
+export function uninstallMod() {
+  if (!modInstalled()) return { ok: true, message: '' };
+  const a = claude(['uninstall', PLUGIN]);
+  const b = claude(['marketplace', 'remove', 'inject']);
+  if (a.ok && b.ok) return { ok: true, message: `/inject command removed (plugin ${PLUGIN})` };
+  return { ok: false, message: `could not remove the /inject command; run:\n${manual([`uninstall ${PLUGIN}`, 'marketplace remove inject'])}` };
+}
+
+export function modInstalled() {
+  try {
+    const base = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+    const plugins = JSON.parse(fs.readFileSync(path.join(base, 'plugins', 'installed_plugins.json'), 'utf8')).plugins;
+    return Array.isArray(plugins?.[PLUGIN]) && plugins[PLUGIN].length > 0;
+  } catch {
+    return false;
+  }
+}

package/src/adapters/claude-code/output.js

@@ -0,0 +1,39 @@
+// Turns claimed messages into Claude Code hook output.
+
+import { formatNotes, formatUrgent } from '../../core/format.js';
+
+export const BOUNDARY = {
+  PreToolUse: 'before-tool',
+  PostToolUse: 'after-tool',
+  PostToolUseFailure: 'after-tool',
+};
+
+/** Short description of a tool call, e.g. "Bash: npm test". */
+export function describeTool(name, input) {
+  if (!name) return null;
+  const i = input || {};
+  const detail = i.command ?? i.file_path ?? i.notebook_path ?? i.path ?? i.pattern ?? i.url ?? i.query ?? i.description;
+  if (detail == null) return name;
+  const s = String(detail).replace(/\s+/g, ' ').trim();
+  return `${name}: ${s.length > 120 ? s.slice(0, 119) + '…' : s}`;
+}
+
+/** Turn claimed messages into Claude Code hook output (null = no output). */
+export function buildOutput(event, messages) {
+  if (!messages.length) return null;
+  if (BOUNDARY[event] === 'before-tool') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: event,
+        permissionDecision: 'deny',
+        permissionDecisionReason: formatUrgent(messages),
+      },
+    };
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName: event,
+      additionalContext: formatNotes(messages),
+    },
+  };
+}

package/src/adapters/claude-code/plain.js

@@ -0,0 +1,47 @@
+// Plain-`claude` mode: `/inject <msg>` in a session that was not started with
+// the inject wrapper (normal urgency only).
+//
+// There is no wrapper process to hold a queue. The /inject command, registered
+// by the mod in mod/ with immediate: true, appends each message to a per-session
+// file in pendingDir(). The PostToolUse hooks claim that file at the next tool
+// boundary. Claiming renames the file first, which is atomic, so parallel tool
+// calls can't deliver a message twice.
+//
+// (A hook can't catch "/inject": in an interactive session Claude Code answers
+// "Unknown command" before UserPromptSubmit fires.)
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Under the user's Claude config dir, not /tmp: another local user must not be
+// able to plant messages for this user's sessions. Keep in sync with the mod
+// (mod/hooks/register.js) and plainGuard() in install.js.
+export function pendingDir() {
+  return path.join(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'inject-pending');
+}
+
+const validId = (id) => typeof id === 'string' && /^[\w-]+$/.test(id);
+
+/** Takes all pending messages for a session. */
+export function claim(sessionId, { dir = pendingDir() } = {}) {
+  if (!validId(sessionId)) return [];
+  const file = path.join(dir, `${sessionId}.jsonl`);
+  const mine = `${file}.claimed-${process.pid}`;
+  try {
+    fs.renameSync(file, mine);
+  } catch {
+    return [];
+  }
+  try {
+    return fs
+      .readFileSync(mine, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((l) => ({ ...JSON.parse(l), urgency: 'normal' }));
+  } catch {
+    return [];
+  } finally {
+    fs.rmSync(mine, { force: true });
+  }
+}

package/src/adapters/claude-code/prompt-hook.js

@@ -0,0 +1,20 @@
+// Claude Code UserPromptSubmit hook. Runs in every session, with or without
+// the inject wrapper, once per prompt you send.
+//
+// Logs prompts typed while Claude is working (they go into Claude Code's own
+// queue) to .steer/fixes.jsonl. Prints nothing; never blocks or changes a prompt.
+// Never throws; any failure exits 0.
+
+import { handlePrompt } from './prompt.js';
+
+async function main() {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) data += chunk;
+  handlePrompt(JSON.parse(data), { projectDir: process.env.CLAUDE_PROJECT_DIR });
+}
+
+main().then(
+  () => process.exit(0),
+  () => process.exit(0),
+);

package/src/adapters/claude-code/prompt.js

@@ -0,0 +1,14 @@
+// Decides what the UserPromptSubmit hook does with a prompt. See prompt-hook.js.
+//
+// It only logs messages typed into Claude Code's own queue mid-turn. It never
+// blocks or changes a prompt. (/inject is handled by the mod, not here.)
+
+import { recordPrompt } from './steering.js';
+
+/** @returns {null} the hook prints nothing */
+export function handlePrompt(input, { projectDir } = {}) {
+  // /inject commands are queued and logged by the mod and the tool hooks.
+  if (typeof input.prompt === 'string' && /^\s*\/inject\b/.test(input.prompt)) return null;
+  recordPrompt(input, { projectDir });
+  return null;
+}

package/src/adapters/claude-code/steering.js

@@ -0,0 +1,98 @@
+// Logs messages typed into Claude Code's own queue mid-turn, so plain
+// `claude` sessions (not started with inject) still record steering in
+// .steer/fixes.jsonl.
+//
+// Claude Code fires UserPromptSubmit as soon as you press Enter, including on
+// a message it queues while Claude is working. A queued message carries the
+// running turn's prompt_id; a new turn gets a new one. So we remember the last
+// prompt_id per session and log a prompt that repeats it.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { appendFix } from '../../core/log.js';
+import { describeTool } from './output.js';
+
+const TAIL_BYTES = 512 * 1024;
+
+export function stateDir() {
+  return path.join(process.env.XDG_RUNTIME_DIR || os.tmpdir(), 'inject-turns');
+}
+
+/**
+ * @param {{session_id?:string, prompt_id?:string, prompt?:string,
+ *          transcript_path?:string, cwd?:string}} input UserPromptSubmit input
+ * @returns {boolean} whether a mid-turn message was logged
+ */
+export function recordPrompt(input, { dir = stateDir(), projectDir, now = new Date() } = {}) {
+  const { session_id: sessionId, prompt_id: promptId, prompt } = input;
+  if (!sessionId || !promptId || typeof prompt !== 'string') return false;
+  if (!/^[\w-]+$/.test(sessionId)) return false;
+
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, sessionId);
+  let current = null;
+  try {
+    current = fs.readFileSync(file, 'utf8');
+  } catch {
+    // First prompt of this session.
+  }
+  if (current !== promptId) {
+    fs.writeFileSync(file, promptId);
+    return false;
+  }
+
+  const text = prompt.trim();
+  if (!text) return false;
+  const ts = now.toISOString();
+  return appendFix(projectDir || input.cwd || process.cwd(), { text, urgency: 'normal', queuedAt: ts }, {
+    agent: 'claude-code',
+    deliveredAt: null,
+    event: 'claude-code-queue',
+    doing: lastToolActivity(input.transcript_path),
+    sessionId,
+  });
+}
+
+/** "running Bash: npm test" / "just ran Edit: src/a.ts", from the transcript tail. */
+export function lastToolActivity(transcriptPath) {
+  if (!transcriptPath) return null;
+  let lines;
+  try {
+    const fd = fs.openSync(transcriptPath, 'r');
+    try {
+      const { size } = fs.fstatSync(fd);
+      const len = Math.min(size, TAIL_BYTES);
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, size - len);
+      lines = buf.toString('utf8').split('\n');
+      if (len < size) lines.shift(); // partial first line
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+
+  const finished = new Set();
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let entry;
+    try {
+      entry = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    const content = entry?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block?.type === 'tool_result') finished.add(block.tool_use_id);
+    }
+    const uses = content.filter((b) => b?.type === 'tool_use');
+    if (entry.message.role === 'assistant' && uses.length) {
+      const use = uses[uses.length - 1];
+      const tool = describeTool(use.name, use.input);
+      return `${finished.has(use.id) ? 'just ran' : 'running'} ${tool}`;
+    }
+  }
+  return null;
+}

package/src/adapters/index.js

@@ -0,0 +1,8 @@
+import claudeCode from './claude-code/index.js';
+
+/** @type {Record<string, import('./types.js').Adapter>} */
+export const adapters = {
+  [claudeCode.id]: claudeCode,
+};
+
+export const defaultAdapter = claudeCode;

package/src/adapters/types.js

@@ -0,0 +1,28 @@
+// The contract an agent adapter fulfils. The wrapper, queue, log and
+// interceptor are agent-neutral; an adapter only knows how to start its agent
+// and how to plug a hook into it.
+//
+// A hook process connects to $INJECT_DIR/sock and sends
+//   {op:'claim', boundary:'before-tool'|'after-tool', agent, event, doing,
+//    projectDir, sessionId}
+// then turns the returned messages into the agent's hook output:
+//   before-tool + messages -> block the tool call with formatUrgent(messages)
+//   after-tool  + messages -> add formatNotes(messages) as context
+//
+// To add an agent (e.g. Codex), create src/adapters/<id>/ exporting an
+// Adapter and a hook entry point, and register it in src/adapters/index.js.
+
+/**
+ * @typedef {object} Adapter
+ * @property {string} id            stable id, recorded in fixes.jsonl
+ * @property {string} name          human-readable name
+ * @property {string} command       executable the wrapper starts
+ * @property {() => {path:string, changed:boolean}} install    register hooks
+ * @property {() => {path:string, changed:boolean}} uninstall  remove hooks
+ * @property {() => boolean} isInstalled
+ * @property {() => {ok:boolean, message:string}} [installMod]    optional: plain-session /inject command
+ * @property {() => {ok:boolean, message:string}} [uninstallMod]
+ * @property {() => boolean} [modInstalled]
+ */
+
+export {};

package/src/cli.js

@@ -0,0 +1,40 @@
+// inject [agent args...]   run the agent with /inject interception
+// inject --install         register hooks (one time)
+// inject --uninstall       remove hooks
+//
+// Everything other than the two flags above is passed to the agent unchanged,
+// so `inject --resume` behaves like `claude --resume`.
+
+import { defaultAdapter } from './adapters/index.js';
+import { run } from './wrapper/run.js';
+
+export async function main(argv) {
+  const adapter = defaultAdapter;
+
+  if (argv[0] === '--install' || argv[0] === '--uninstall') {
+    try {
+      const { path, changed } = argv[0] === '--install' ? adapter.install() : adapter.uninstall();
+      const verb = argv[0] === '--install' ? 'installed in' : 'removed from';
+      console.log(changed ? `inject: ${adapter.name} hooks ${verb} ${path}` : `inject: nothing to change in ${path}`);
+      if (changed) console.log(`inject: previous settings saved to ${path}.inject-backup`);
+      if (changed && argv[0] === '--install') {
+        console.log(`inject: already-running ${adapter.name} sessions pick this up after a restart.`);
+      }
+      const mod = argv[0] === '--install' ? adapter.installMod?.() : adapter.uninstallMod?.();
+      if (mod?.message) console[mod.ok ? 'log' : 'error'](`inject: ${mod.message}`);
+    } catch (err) {
+      console.error(`inject: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (!adapter.isInstalled()) {
+    process.stderr.write(
+      `inject: ${adapter.name} hooks are not installed, so /inject messages won't be delivered.\n` +
+        `        Run \`inject --install\` once, then start inject again.\n`,
+    );
+  }
+
+  await run(adapter, argv);
+}

package/src/core/format.js

@@ -0,0 +1,32 @@
+// Wording the agent sees. Agent-neutral: adapters wrap these strings in
+// whatever output shape their hook system expects.
+
+function bullets(msgs) {
+  if (msgs.length === 1) return msgs[0].text;
+  return msgs.map((m) => `- ${m.text}`).join('\n');
+}
+
+/** Context for normal notes delivered after a tool call. */
+export function formatNotes(msgs) {
+  return [
+    `[inject] The user sent ${msgs.length === 1 ? 'a message' : 'messages'} while you were working. You were not interrupted:`,
+    '',
+    bullets(msgs),
+    '',
+    'Take this into account from your next step on.',
+  ].join('\n');
+}
+
+/** Reason shown to the agent when an urgent message blocks a tool call. */
+export function formatUrgent(msgs) {
+  const urgent = msgs.filter((m) => m.urgency === 'urgent');
+  const notes = msgs.filter((m) => m.urgency !== 'urgent');
+  const lines = [
+    '[inject] This tool call was blocked and did not run, because the user sent an urgent message while you were working:',
+    '',
+    bullets(urgent),
+  ];
+  if (notes.length) lines.push('', 'Also from the user:', '', bullets(notes));
+  lines.push('', 'Re-plan with this in mind before you continue. If the blocked call is still right, you may retry it.');
+  return lines.join('\n');
+}

package/src/core/ipc.js

@@ -0,0 +1,61 @@
+// One-request-per-connection JSON protocol over the session's unix socket.
+//
+// Request:  {"op":"claim","boundary":"before-tool"|"after-tool","agent":..,
+//            "event":..,"doing":..,"projectDir":..,"sessionId":..}
+// Response: {"messages":[{id,text,urgency,queuedAt}, ...]}
+
+import net from 'node:net';
+
+const MAX_REQUEST_BYTES = 1 << 20;
+
+/** @param {(req:object)=>object} handle */
+export function listen(sockPath, handle) {
+  const server = net.createServer((conn) => {
+    let buf = '';
+    conn.setEncoding('utf8');
+    conn.on('data', (chunk) => {
+      buf += chunk;
+      if (buf.length > MAX_REQUEST_BYTES) return conn.destroy();
+      const nl = buf.indexOf('\n');
+      if (nl === -1) return;
+      let reply;
+      try {
+        reply = handle(JSON.parse(buf.slice(0, nl)));
+      } catch (err) {
+        reply = { error: String(err && err.message ? err.message : err) };
+      }
+      conn.end(JSON.stringify(reply) + '\n');
+    });
+    conn.on('error', () => {});
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(sockPath, () => resolve(server));
+  });
+}
+
+export function request(sockPath, req, timeoutMs = 3000) {
+  return new Promise((resolve, reject) => {
+    const conn = net.createConnection(sockPath);
+    let buf = '';
+    const timer = setTimeout(() => {
+      conn.destroy();
+      reject(new Error('timed out waiting for the inject wrapper'));
+    }, timeoutMs);
+    conn.setEncoding('utf8');
+    conn.on('connect', () => conn.write(JSON.stringify(req) + '\n'));
+    conn.on('data', (chunk) => (buf += chunk));
+    conn.on('end', () => {
+      clearTimeout(timer);
+      try {
+        resolve(JSON.parse(buf));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    conn.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}

package/src/core/log.js

@@ -0,0 +1,34 @@
+// Appends one JSON line per injected message to <project>/.steer/fixes.jsonl.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function logPath(projectDir) {
+  return path.join(projectDir, '.steer', 'fixes.jsonl');
+}
+
+/**
+ * @param {string} projectDir
+ * @param {{text:string, urgency:string, queuedAt:string}} msg
+ * @param {{agent?:string, deliveredAt?:string|null, event?:string|null,
+ *          doing?:string|null, sessionId?:string|null}} delivery
+ */
+export function appendFix(projectDir, msg, delivery) {
+  const record = {
+    ts: msg.queuedAt,
+    text: msg.text,
+    urgency: msg.urgency,
+    agent: delivery.agent ?? null,
+    delivered_at: delivery.deliveredAt ?? null,
+    delivered_via: delivery.event ?? null,
+    doing: delivery.doing ?? null,
+    session_id: delivery.sessionId ?? null,
+  };
+  try {
+    fs.mkdirSync(path.dirname(logPath(projectDir)), { recursive: true });
+    fs.appendFileSync(logPath(projectDir), JSON.stringify(record) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}