agentbox-app 0.1.12 → 0.1.13

package/main/harnesses/claude-stream.mjs

@@ -0,0 +1,208 @@
+import { hookFailure } from '../../shared/hook-failure.mjs';
+import { SAYING_CAP } from '../codex.mjs';
+
+// The stream's own metadata, kept on the session object: the session id (what
+// a personal reply resumes) and the final result message (what the founder
+// reads). Recorded for every session because it is one parse we are already
+// paying for; acted on where someone needs it.
+export function captureStream(session, line) {
+  try {
+    const obj = JSON.parse(line);
+    if (obj.session_id) session.sessionId = obj.session_id;
+    if (obj.type === 'result') {
+      session.result = String(obj.result ?? '');
+      session.resultIsError = !!obj.is_error;
+      // A run cannot end with helpers still out. Cleared here as well as on
+      // exit so the number can never outlive the thing it counts. Unless
+      // something is still out in the background: then this was a turn
+      // ending, not the run, and the session stays open for it.
+      if (!session.child?.waitingOn?.().length) session.helperIds?.clear();
+    }
+    noteClaimAnswer(session, obj);
+    countHelpers(session, obj);
+  } catch {}
+}
+
+// Whether this run was refused its own row, off the claim call and its reply.
+// `closingMessageIsTheAnswer` reads it: a refused worker is told to end saying
+// nothing, and whatever it does say must not land on a row someone else holds.
+// A later claim that succeeds clears it.
+function noteClaimAnswer(session, obj) {
+  const blocks = Array.isArray(obj?.message?.content) ? obj.message.content : [];
+  for (const b of blocks) {
+    if (obj.type === 'assistant' && b?.type === 'tool_use' && /claim_work_item$/.test(b.name ?? '')
+      && (!b.input?.id || b.input.id === session.itemId)) {
+      (session.claimCalls ??= new Set()).add(b.id);
+    }
+    if (obj.type === 'user' && b?.type === 'tool_result' && session.claimCalls?.has(b.tool_use_id)) {
+      const text = typeof b.content === 'string' ? b.content
+        : (b.content ?? []).map((c) => c?.text ?? '').join('');
+      if (/"claimed"\s*:\s*false/.test(text)) session.claimRefused = true;
+      else if (/"claimed"\s*:\s*true/.test(text)) session.claimRefused = false;
+    }
+  }
+}
+
+/**
+ * `--include-partial-messages` puts `stream_event` frames on the same stdout
+ * the finished messages come down. This keeps the CURRENT text block on the
+ * session as it grows, and nothing else: no thinking, no tool arguments, and
+ * nothing written to disk. It dies with the process, exactly like `tail`.
+ *
+ * ONE BLOCK AT A TIME, AND THAT IS THE POINT. A finished message becomes ONE
+ * trace line per text block (`traceStreamLine`), so holding exactly one block
+ * here means the live string and the traced string are the same string, and
+ * the thread can drop the live copy the moment the traced one arrives without
+ * guessing (`itemThread`, renderer/src/item-thread.ts).
+ *
+ * IT IS NOT CLEARED WHEN THE MESSAGE FINISHES, and that is deliberate. The
+ * trace is written on one channel and read on another, so clearing it here
+ * would blink the sentence off her screen for however long the read takes and
+ * then put it back. The renderer suppresses it the moment the thread has it,
+ * which is a comparison rather than a race.
+ *
+ * Returns true when the string moved, which is what earns a push.
+ */
+export function streamingText(session, line) {
+  try {
+    const obj = JSON.parse(line);
+    if (obj.type !== 'stream_event') return false;
+    const event = obj.event ?? {};
+    // A new message. Whatever the last one ended on is the last one's, and the
+    // trace has it by now.
+    if (event.type === 'message_start') {
+      session.saying = '';
+      session.sayingAt = 0;
+      return true;
+    }
+    if (event.type === 'content_block_start') {
+      // Only a text block resets it. A tool call or a thought starting means
+      // this message has moved on from prose, and the block already typed
+      // stays on screen until the trace delivers the same words.
+      if (event.content_block?.type !== 'text') return false;
+      session.saying = '';
+      session.sayingAt = Date.now();
+      return true;
+    }
+    if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
+      const piece = String(event.delta.text ?? '');
+      if (!piece) return false;
+      if (!session.sayingAt) session.sayingAt = Date.now();
+      const next = (session.saying ?? '') + piece;
+      // Past the cap this stops being a sentence she is reading. Dropped
+      // rather than cut, because a cut string never matches the traced one and
+      // would sit under it on her screen forever.
+      session.saying = next.length > SAYING_CAP ? '' : next;
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// HOW MANY HELPERS THIS SESSION HAS OUT RIGHT NOW.
+//
+// THE ONLY TWO EVENTS THAT MATTER, and they bracket a helper exactly. Measured
+// on Claude Code 2.1.246 over a real four-helper run (the probe is written up
+// in decisions.md, 08-26): `task_started` carries a fresh `task_id`, and
+// `task_updated` carries a `patch.status` of `completed` for that same id. Four
+// starts, four completions, no id seen twice and none left open. So a set of
+// live ids, and its size is the number.
+//
+// A SET AND NOT A COUNTER, because a counter cannot survive a duplicate: the
+// stream is read line by line off a pipe, and one repeated line would leave the
+// page saying five helpers are working for the rest of the run with nothing
+// able to correct it. Adding an id twice is free.
+//
+// NESTED HELPERS ARE COUNTED THE SAME. `spawn_depth` says how deep a helper
+// sits, and this deliberately ignores it: a helper's helper is still a
+// subagent working on her task.
+//
+// THE LEAD IS NOT IN THIS NUMBER AND NEVER HAS BEEN, which is what the line
+// drawn off it was getting wrong until 2026-08-27. Only a `task_started` id is
+// ever added, and the lead has no `task_started` of its own.It is, so
+// `shortWord` in renderer/src/live-line.ts now says Subagents, unhyphenated on
+// her call of 2026-08-27 and on a count of the spelling in the Claude Code
+// build she runs. If this ever starts counting the lead as well, that word has
+// to move with it. DID THIS RUN LEAVE HER ANYTHING TO READ?
+//
+// The rule that divides the two writers, kept in one named place because
+// getting it wrong is silence, and silence is the failure that matters most:
+//
+//   - said nothing at all   -> the supervisor speaks for it (sayTheRunDied)
+//   - said something wrong  -> the supervisor speaks for it, in OUR words
+//   - said something real   -> it speaks for itself, untouched
+//
+// The middle line is the one that was missing. Both writers used to exclude an
+// error result: `speaksForTheSession` because raw CLI text must never reach her
+// row, and this one because it only looked for a result that was absent. Each
+// was right on its own and together they left the case that matters most with
+// no writer at all.
+export function saidNothingSheCanUse(session) {
+  return session?.result == null || !!session.resultIsError;
+}
+
+export function countHelpers(session, obj) {
+  if (obj?.type !== 'system') return;
+  if (obj.subtype === 'task_started' && obj.task_id) {
+    (session.helperIds ??= new Set()).add(obj.task_id);
+  } else if (obj.subtype === 'task_updated' && obj.task_id) {
+    // Anything that is not still running ends it. The measured value is
+    // `completed`, and a helper that fails or is cancelled has equally stopped
+    // working, so the test is what it is NOT rather than a list of endings we
+    // would have to keep in step with the CLI.
+    const status = obj.patch?.status;
+    if (status && status !== 'in_progress' && status !== 'running') session.helperIds?.delete(obj.task_id);
+  }
+}
+
+// The persisted trace line: fuller than the tail. Tool calls carry their key
+// input (the file written, the command run), because "tool: Bash" answers
+// nothing when the founder asks what a session actually did.
+export function traceStreamLine(line) {
+  try {
+    const obj = JSON.parse(line);
+    const at = new Date().toISOString().slice(11, 19);
+    const hook = hookFailure(obj);
+    if (hook) return `${at}  ${hook}`;
+    if (obj.type === 'assistant' && obj.message?.content) {
+      const parts = [];
+      for (const c of obj.message.content) {
+        if (c.type === 'text' && c.text?.trim()) parts.push(c.text.trim());
+        if (c.type === 'tool_use') {
+          const input = c.input ?? {};
+          const hint = input.file_path ?? input.path ?? input.command ?? input.title ?? input.description ?? input.id ?? '';
+          parts.push(`[${c.name}] ${String(hint).slice(0, 200)}`);
+        }
+      }
+      return parts.length ? parts.map((p) => `${at}  ${p}`).join('\n') : null;
+    }
+    if (obj.type === 'result') {
+      const flavor = `${obj.subtype ?? 'ok'}${obj.is_error ? ' ERROR' : ''} · ${obj.num_turns ?? '?'} turns`;
+      return `\n${at}  == RESULT (${flavor}) ==\n${String(obj.result ?? '').slice(0, 4000)}`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// Stream-json lines are verbose; the In Progress tail wants the gist.
+export function summarizeStreamLine(line) {
+  try {
+    const obj = JSON.parse(line);
+    const hook = hookFailure(obj);
+    if (hook) return hook;
+    if (obj.type === 'assistant' && obj.message?.content) {
+      const text = obj.message.content.filter((c) => c.type === 'text').map((c) => c.text).join(' ');
+      const tools = obj.message.content.filter((c) => c.type === 'tool_use').map((c) => c.name);
+      if (tools.length) return `tool: ${tools.join(', ')}`;
+      if (text) return text.slice(0, 300);
+    }
+    if (obj.type === 'result') return `done: ${String(obj.result ?? '').slice(0, 200)}`;
+    return null;
+  } catch {
+    return line.slice(0, 200);
+  }
+}

package/main/harnesses/claude.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { harnessDefinition } from '../../shared/harness-definitions.mjs';
+import { EFFORT_LEVELS } from '../../shared/effort-levels.mjs';
+import { storeRootEnv } from '../store/home.mjs';
+import { resolveClaudeBin } from '../claude-bin.mjs';
+import { claudeModelRows } from '../claude-models.mjs';
+import { linkAccountTooling } from '../account-tooling.mjs';
+import { streamInputArgs, attachClaudeInput } from '../claude-input.mjs';
+import { claudeLaunchEnv } from '../claude-launch-env.mjs';
+import { claudeActivity } from '../agent-activity.mjs';
+import { captureStream, streamingText, summarizeStreamLine, traceStreamLine } from './claude-stream.mjs';
+import { definitionMethods, commonUpdatePlan } from './common.mjs';
+const definition = harnessDefinition('claude');
+
+export const claudeHarness = {
+  ...definitionMethods(definition),
+  discover: resolveClaudeBin,
+  launchEnv: claudeLaunchEnv,
+  models: ({ bin } = {}) => claudeModelRows({ bin: bin ?? null }).map(m => ({ id: m.alias, label: m.label })),
+  defaultModel: () => null,
+  workspaceModel: () => null,
+  profileHome: () => null,
+  effortLevels: () => EFFORT_LEVELS.map(e => e.id),
+  profiles: sup => sup._profiles(),
+  signedIn: () => true,
+  profileEnv: (env, profile) => profile === 'default' ? env : { ...env, [definition.homeEnv]: profile },
+  signInFiles({ folder, home }) {
+    if (folder) return definition.credentialFiles.map(file => path.join(folder, file));
+    const dir = path.join(home, '.claude');
+    return [path.join(home, '.claude.json'), ...definition.credentialFiles.map(file => path.join(dir, file))];
+  },
+  tooling: profile => linkAccountTooling(profile),
+  spawn(sup, plan, { cwd, item, profile, env }) {
+    // The binary is the one this definition names, not a field spelled out
+    // here: that is the last place an engine of this family needed code.
+    return spawn(sup.config[definition.binKey], streamInputArgs(definition.run, plan.args), {
+      cwd,
+      env: { ...claudeLaunchEnv(sup.config[definition.binKey], env), STORE_ACCOUNT_ID: sup.config.accountId, ...storeRootEnv(sup.config.storeRoot),
+        ...(profile !== 'default' ? { [definition.homeEnv]: profile } : {}),
+        ZERO_PRODUCT: item.product, ZERO_ITEM: item.id, ...sup.memoryGateEnv(item) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  },
+  readers: () => ({ capture: captureStream, stream: streamingText, summarize: summarizeStreamLine, trace: traceStreamLine, activity: claudeActivity }),
+  subscribe(child, _session, absorb) {
+    let buffer = '';
+    child.stdout.on('data', data => {
+      buffer += data.toString();
+      let index;
+      while ((index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+        if (line.trim()) absorb(line);
+      }
+    });
+  },
+  attachInput: child => attachClaudeInput(child),
+  transcript(sup, rec) {
+    if (!rec?.sessionId) return null;
+    const home = rec.profile && rec.profile !== 'default' ? rec.profile : path.join(os.homedir(), '.claude');
+    const projects = path.join(home, 'projects');
+    const slug = String(rec.cwd ?? '').replace(/[^a-zA-Z0-9]/g, '-');
+    const direct = path.join(projects, slug, `${rec.sessionId}.jsonl`);
+    if (fs.existsSync(direct)) return direct;
+    try { for (const dir of fs.readdirSync(projects)) {
+      const file = path.join(projects, dir, `${rec.sessionId}.jsonl`);
+      if (fs.existsSync(file)) return file;
+    } } catch {}
+    return null;
+  },
+  change: () => null,
+  release: () => {},
+  memoryGate: (sup, item) => sup.memoryGateEnv(item),
+  smallModelArgs: (prompt, model) => ['-p', prompt, '--model', model],
+  updateSettings: ({ home }) => {
+    try { return JSON.parse(fs.readFileSync(path.join(process.env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'settings.json'), 'utf8')); }
+    catch { return {}; }
+  },
+  updatePlan: options => commonUpdatePlan(definition, options, ({ bin, real, home, channel, name }) =>
+    real.startsWith(path.join(home, '.local/share/claude/versions') + '/')
+      ? { name, file: bin, args: ['update'], feed: `https://downloads.claude.ai/claude-code-releases/${channel}`, format: 'text' } : null),
+};

package/main/harnesses/codex.mjs

@@ -0,0 +1,65 @@
+import path from 'node:path';
+import { harnessDefinition } from '../../shared/harness-definitions.mjs';
+import { resolveCodexBin } from '../codex-bin.mjs';
+import { codexLaunchEnv } from '../codex-launch-env.mjs';
+import { codexModels, codexDefaultModel, codexModelLevels } from '../codex-models.mjs';
+import { codexTranscriptFile, workerThreadParams } from '../codex-session.mjs';
+import { compactCodexThread } from '../codex-compaction.mjs';
+import { captureCodexEvent, codexStreamingText, summarizeCodexEvent, traceCodexEvent, rememberCodexChange, changeFromCodexTurn } from '../codex.mjs';
+import { codexActivity } from '../agent-activity.mjs';
+import { runCodexCommand } from '../provider-commands.mjs';
+import { definitionMethods, commonUpdatePlan } from './common.mjs';
+const definition = harnessDefinition('codex');
+
+export const codexHarness = {
+  ...definitionMethods(definition),
+  discover: resolveCodexBin,
+  launchEnv: codexLaunchEnv,
+  models: (options = {}) => codexModels(options),
+  defaultModel: (options = {}) => codexDefaultModel(options),
+  workspaceModel: sup => sup._codexWorkspaceModel(),
+  profileHome: (sup, profile) => sup._codexProfileHome(profile),
+  effortLevels: (model, options = {}) => codexModelLevels(model, options),
+  profiles: sup => sup._codexProfiles(),
+  signedIn: (sup, profile) => sup._codexSignedIn(profile),
+  profileEnv: (env, profile, sup) => ({ ...env, [definition.homeEnv]: sup._codexProfileHome(profile) }),
+  tooling: () => null,
+  // Codex carries the person's standing instructions as a thread's
+  // `developerInstructions`, so it needs neither a flag nor a file. It says so
+  // rather than inheriting the refusal meant for an engine that has nowhere to
+  // put them (main/harnesses/instructions-file.mjs).
+  instructions: () => ({ by: 'thread' }),
+  spawn: (sup, plan, context) => sup._spawnCodexWorker(plan, context),
+  readers: () => ({ capture: captureCodexEvent, stream: codexStreamingText, summarize: summarizeCodexEvent, trace: traceCodexEvent, activity: codexActivity }),
+  subscribe(child, session, absorb) {
+    child.on('event', (method, params) => { rememberCodexChange(session, method, params); absorb(method, params); });
+  },
+  attachInput: () => {},
+  transcript: (sup, rec) => rec?.sessionId ? codexTranscriptFile(rec.sessionId, { home: sup._codexProfileHome(rec.profile) }) : null,
+  change: (session, options) => changeFromCodexTurn(session.codexChange ?? [], options),
+  release: (sup, profile) => sup._releaseIdleCodex(profile),
+  usage: sup => sup.codexUsage(),
+  async compact(sup, rec, cwd) {
+    const { client, handshake } = sup._codexServer(sup._codexProfileHome(rec.profile ?? 'default'));
+    const mcpServers = await sup._codexIsolation(client, handshake);
+    const params = workerThreadParams({ cwd, mcpServers, storeServer: null });
+    return compactCodexThread({ server: client, threadId: rec.sessionId, threadParams: params });
+  },
+  settleApproval: (sup, ...args) => sup.settleCodexApproval(...args),
+  approvalChanged: (sup, ...args) => sup.codexCardChanged(...args),
+  memoryGate: sup => sup.codexMemoryGateEnv(),
+  async runCommand(sup, { home, ...operation }) {
+    const { client, handshake } = sup._codexServer(home);
+    await handshake;
+    return runCodexCommand({ server: client, ...operation });
+  },
+  updateSettings: () => ({}),
+  updatePlan: options => commonUpdatePlan(definition, options, ({ bin, real, name }) => {
+    const standalone = real.match(/^(.*)\/packages\/standalone\/(?:releases|current)\//);
+    return standalone ? { name, file: '/bin/bash',
+      args: ['-o', 'pipefail', '-c', '/usr/bin/curl -fsSL --connect-timeout 10 --max-time 60 https://chatgpt.com/codex/install.sh | /bin/sh'],
+      env: { CODEX_HOME: standalone[1], CODEX_INSTALL_DIR: path.dirname(bin) },
+      feed: 'https://releases.openai.com/codex/channels/latest', format: 'codex' } : null;
+  }),
+  smallModelArgs: prompt => ['exec', '--skip-git-repo-check', '--ephemeral', '--ignore-user-config', '--ignore-rules', '-s', 'read-only', '-c', 'model_reasoning_effort=low', prompt],
+};

package/main/harnesses/common.mjs

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { instructionsFor } from './instructions-file.mjs';
+
+/**
+ * THE COMMAND LINE THAT STARTS A WORKER, BUILT FROM THE DEFINITION'S `run`.
+ *
+ * Every flag name here used to be a literal in main/supervisor.mjs, so the
+ * supervisor knew one engine's CLI by heart and a second one of the same family
+ * could not be added without editing it. The order is the order that shipped,
+ * and `tests/a-second-stream-json-engine-is-only-a-definition` holds it there,
+ * because flag order is the kind of thing a refactor silently rewrites.
+ *
+ * ABSENT MEANS CANNOT, not "default". An engine whose `run` has no `effort` is
+ * handed no effort word even when the task names one, which is how a harness
+ * says it lacks a capability without the call site asking who it is. `fork` is
+ * the one pair: a fork is a fork OF something, so it needs a resume as well.
+ */
+export function workerArgsFrom(run, { prompt, grants = [], effort = null, system = null, resumeId = null, fork = false } = {}) {
+  if (!run) return [];
+  const args = [];
+  if (run.print) args.push(run.print, prompt);
+  if (run.outputFormat) args.push(run.outputFormat.flag, run.outputFormat.value);
+  if (run.stream) args.push(...run.stream);
+  args.push(...grants);
+  if (run.effort && effort) args.push(run.effort, effort);
+  if (run.system && system) args.push(run.system, system);
+  if (run.resume && resumeId) args.push(run.resume, resumeId);
+  if (run.fork && fork && resumeId) args.push(run.fork);
+  return args;
+}
+
+export function definitionMethods(definition) {
+  const scrub = definition.scrubPatterns.map(pattern => new RegExp(pattern));
+  return {
+    ...definition,
+    binary: config => config?.[definition.binKey] ?? null,
+    workerArgs: options => workerArgsFrom(definition.run, options),
+    // WHERE THE PERSON'S STANDING INSTRUCTIONS GO on this engine. A flag for
+    // the one that has one, a file named in the definition for the ones that
+    // do not, and a refusal for an engine with neither — because that engine
+    // would answer against rules it was never given, and nothing on screen
+    // would say so.
+    instructions: context => instructionsFor(definition, context),
+    launchEnv: (_bin, env) => ({ ...env }),
+    install: () => ({ file: definition.installer.shell, args: ['-c', `curl -fsSL ${definition.installer.url} | ${definition.installer.pipe}`] }),
+    signIn: bin => ({ file: bin, args: [...definition.loginArgs] }),
+    signInStatus: bin => ({ file: bin, args: [...definition.statusArgs] }),
+    accountKey: profile => `${definition.accountPrefix}${profile}`,
+    workerEnv(input = process.env) {
+      const env = { ...input };
+      for (const key of Object.keys(env)) if (scrub.some(pattern => pattern.test(key))) delete env[key];
+      return env;
+    },
+    signInFiles: ({ folder }) => folder ? definition.credentialFiles.map(file => path.join(folder, file)) : [],
+  };
+}
+
+// Installation-specific work remains in each adapter. The common installers
+// use the same prefix and cask checks for every registered tool.
+export function commonUpdatePlan(definition, { bin, real, home, channel = 'latest' }, native) {
+  if (!path.isAbsolute(bin || '') || !real) return null;
+  const name = definition.label;
+  const brew = real.match(/^(\/opt\/homebrew|\/usr\/local)\/Caskroom\/([^/]+)\//);
+  if (brew && definition.casks.includes(brew[2])) return {
+    name, file: `${brew[1]}/bin/brew`, args: ['upgrade', '--cask', brew[2]],
+    feed: `https://formulae.brew.sh/api/cask/${brew[2]}.json`, format: 'brew',
+  };
+  const tail = `/lib/node_modules/${definition.package}/`;
+  const at = real.indexOf(tail);
+  if (at > 0) {
+    const prefix = real.slice(0, at);
+    return { name, file: path.join(prefix, 'bin/npm'),
+      args: ['install', '--global', '--prefix', prefix, `${definition.package}@${channel}`],
+      env: { PATH: `${prefix}/bin:${process.env.PATH || ''}` },
+      feed: `https://registry.npmjs.org/${definition.package}/${channel}`, format: 'npm' };
+  }
+  return native?.({ bin, real, home, channel, name }) ?? null;
+}

package/main/harnesses/instructions-file.mjs

@@ -0,0 +1,116 @@
+/**
+ * THE PERSON'S STANDING INSTRUCTIONS, FOR AN ENGINE WITH NO SYSTEM PROMPT.
+ *
+ * Claude Code takes them on `--append-system-prompt` and Codex takes them as a
+ * thread's `developerInstructions`. Every other engine we have looked at takes
+ * neither: ACP has no system prompt in the protocol, and OpenCode's server
+ * takes none. So the instructions are the one thing that would arrive nowhere
+ * while everything else about a run looked perfect, and a worker that never
+ * read them is worse than one that failed to start, because it works and
+ * answers against rules it was never given.
+ *
+ * Decided on w-380b06bf53: they go into the file the tool itself reads, and
+ * which file that is lives in the definition as data — AGENTS.md for most of
+ * them, GEMINI.md for Gemini CLI. Same shape as every other name in there.
+ *
+ * TWO RULES THIS FILE IS BUILT AROUND, both of them other people's property.
+ *
+ * NEVER A TRACKED FILE. A task folder is a worktree of somebody's own
+ * repository, and AGENTS.md is frequently committed in one. This codebase has
+ * already paid for writing a tracked file once: every folder that had run the
+ * app reported itself dirty, `releaseTaskFolder` would not reclaim a folder,
+ * and change cards carried files nobody had touched (CLAUDE.md, 2026-10-07).
+ * So the preferred home is the tool's own config directory, which is per-task
+ * and ours; and if a definition does ask for the working folder, a path the
+ * repository tracks is refused rather than written.
+ *
+ * NEVER SOMEBODY ELSE'S WORDS. If the file is already there, what is in it
+ * stays. Only the block between our two markers is rewritten, so resuming a
+ * thread fifty times leaves one block and their own text untouched.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const INSTRUCTIONS_BEGIN = '<!-- agentbox:instructions -->';
+export const INSTRUCTIONS_END = '<!-- /agentbox:instructions -->';
+
+/**
+ * HOW THIS ENGINE CARRIES INSTRUCTIONS: 'flag', 'file', or null for neither.
+ *
+ * Null is the answer that matters. It is not a default to be filled in later;
+ * it is an engine that cannot be offered, because the person's rules would not
+ * reach it and nothing on screen would say so.
+ */
+export function carriesInstructions(definition) {
+  if (definition?.run?.system) return 'flag';
+  if (definition?.instructions?.file) return 'file';
+  return null;
+}
+
+/** The absolute path this engine's instructions belong at, or null. */
+export function instructionsTarget(definition, { cwd, home } = {}) {
+  const spec = definition?.instructions;
+  if (!spec?.file) return null;
+  const root = spec.in === 'cwd' ? cwd : home;
+  return root ? path.join(root, spec.file) : null;
+}
+
+/** Whether this repository has the file under version control. */
+export function fileIsTracked(file, cwd) {
+  const where = cwd ?? path.dirname(file);
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', file], { cwd: where, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;   // not tracked, or not a repository at all
+  }
+}
+
+/**
+ * Put the instructions in the file, and nothing else in it out.
+ *
+ * Idempotent on purpose: a thread resumes many times and each run writes the
+ * block again, so the test that matters is that there is exactly one of them
+ * afterwards. Returns the path written.
+ */
+export function writeInstructions({ file, text, cwd = null, tracked = null }) {
+  if (!file) throw Error('There is nowhere to write these instructions');
+  const isTracked = tracked ?? fileIsTracked(file, cwd);
+  if (isTracked) {
+    // Their file, under their version control. Writing it would dirty the
+    // worktree and could ride into the change this task is for.
+    throw Error(`${file} is tracked by this repository, so the instructions cannot be written there`);
+  }
+  const block = `${INSTRUCTIONS_BEGIN}\n${text}\n${INSTRUCTIONS_END}`;
+  let before = '';
+  try { before = fs.readFileSync(file, 'utf8'); } catch {}
+  let next;
+  const begins = before.indexOf(INSTRUCTIONS_BEGIN);
+  const ends = before.indexOf(INSTRUCTIONS_END);
+  if (begins >= 0 && ends > begins) {
+    next = before.slice(0, begins) + block + before.slice(ends + INSTRUCTIONS_END.length);
+  } else {
+    next = before ? `${before.replace(/\s*$/, '')}\n\n${block}\n` : `${block}\n`;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next);
+  return file;
+}
+
+/**
+ * The `instructions` operation every harness answers.
+ *
+ * `{ by: 'flag' }` for an engine whose command line carries them, so nothing
+ * is written and the existing path is untouched. `{ by: 'file', file }` once
+ * they are on disk. An engine that carries them neither way has no business
+ * being offered, so this throws rather than returning a shrug.
+ */
+export function instructionsFor(definition, { cwd, home, text } = {}) {
+  const how = carriesInstructions(definition);
+  if (how === 'flag') return { by: 'flag' };
+  if (how !== 'file') throw Error(`${definition?.label ?? 'This engine'} has nowhere to put standing instructions`);
+  const file = instructionsTarget(definition, { cwd, home });
+  if (!text) return { by: 'file', file, written: false };
+  return { by: 'file', file: writeInstructions({ file, text, cwd }), written: true };
+}