@indigoai-us/hq-cli 5.345.191 → 5.345.194

package/dist/lib/signals/steps/extract.js

@@ -0,0 +1,793 @@
+/**
+ * extract step: run the ontology worker's process-source skill on each
+ * unprocessed item of every local-run source channel, one model turn per
+ * item, under the main local bot's coding-tool login.
+ *
+ * Flow per channel: ontology-source-worklist.sh (run by the step, never by
+ * the model) -> one turn per item that writes candidates only through a
+ * per-item wrapper of ontology-candidate.sh -> validate the new candidates ->
+ * --mark-done only when the turn succeeded.
+ *
+ * Isolation. A turn reads an untrusted transcript, so the runtime flags, not
+ * HQ's settings, decide what the model can do:
+ * - cwd is a fresh temp dir outside HQ holding the wrapper. The wrapper pins
+ *   --company, --audience and --source-ref to the item and refuses
+ *   --body-file, so a candidate can only carry text the model writes.
+ * - Reads are limited to the item's channel folder in ctx.company.
+ * - After the turn every company's _candidates is diffed, and only the new
+ *   files carrying this item's source_ref are touched. One outside ctx.company
+ *   is deleted and the item fails (unless that company has its own source item
+ *   of the same name); one in ctx.company that fails validation is deleted.
+ *   New files from other writers (other companies' bots, other sources,
+ *   garden's moves) are left alone.
+ * - Worklist items whose path or audience could break out of the prompt or
+ *   the channel folder are refused before any turn.
+ *
+ * Runtime flags, checked 2026-11-01 against `claude --help` (2.1.316) and
+ * `codex exec --help` (0.153.4) on Corey's Mac:
+ *   claude -p <prompt> --output-format stream-json --verbose
+ *     --permission-mode dontAsk --permission-prompts none --restricted
+ *     --tools Read,Bash --strict-mcp-config --mcp-config {"mcpServers":{}}
+ *     --disable-slash-commands --no-session-persistence
+ *     --max-turns <n> --max-budget-usd <x> --add-dir <channel dir>
+ *     --allowedTools Read(//<channel dir>/**) "Bash(bash <wrapper> *)"
+ *   dontAsk denies every tool call no allow rule covers. --restricted ignores
+ *   the user, project and local settings files (so no HQ or user allow rules,
+ *   hooks or plugins) and confines file tools to the working directories.
+ *   --tools leaves only Read and Bash in the tool set; --strict-mcp-config with
+ *   an empty --mcp-config loads no MCP server. (`--bare` is not used: it needs
+ *   an API key and skips the login.) An older claude without --restricted
+ *   exits on the unknown flag, so the item fails and is retried.
+ *   codex -a never exec --json --skip-git-repo-check --ephemeral
+ *     --ignore-user-config --ignore-rules -C <turn dir>
+ *     -c default_permissions="hq_signals_extract"
+ *     -c permissions.hq_signals_extract.filesystem={...}
+ *     -c permissions.hq_signals_extract.network.enabled=false <prompt>
+ *   The permission profile reads only the platform minimum, the codex install,
+ *   the turn dir, core/scripts, the company's knowledge preferences and the
+ *   item's channel folder, and writes only the company's _candidates folders.
+ *   --ignore-user-config drops ~/.codex/config.toml (its MCP servers);
+ *   --ignore-rules drops execpolicy allow rules. Codex has no turn cap flag;
+ *   the per-item timeout is its only limit, and it reports no cost.
+ *   grok: src/lib/bot/runtime/grok.ts has no restricted tool or sandbox
+ *   mode, so the step refuses it.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { readBotConfig, effectiveBotKind, isBotRuntimeId } from "../../bot/config.js";
+import { botsRoot } from "../../bot/paths.js";
+import { CLAUDE_LOGGED_OUT_RE } from "../../hot-channels/signals-pass.js";
+import { assertAllowedPath, assertNoEscapingLinks, guardedRemove, realRelPath } from "../write-guard.js";
+export const EXTRACT_SIGNAL_TYPES = [
+    "action_item",
+    "commitment",
+    "decision",
+    "risk",
+    "question",
+    "key_point",
+    "participant_contribution",
+    "summary",
+];
+const ENTITY_TYPES = ["person", "project", "company", "concept"];
+export const DEFAULT_WORKLIST_LIMIT = 20;
+export const DEFAULT_TURN_TIMEOUT_MS = 10 * 60_000;
+const SCRIPT_TIMEOUT_MS = 60_000;
+export const CODEX_PERMISSION_PROFILE = "hq_signals_extract";
+export const CANDIDATE_WRAPPER_NAME = "write-candidate.sh";
+/** The only tools a claude turn may use: Read inside the channel folder and the pinned wrapper. */
+export function claudeAllowedTools(channelDir, wrapperPath) {
+    // A rule path that starts with `//` is absolute.
+    return [`Read(/${channelDir}/**)`, `Bash(bash ${wrapperPath} *)`];
+}
+/** First personal bot under ~/.hq/bots (by name) with a readable config. */
+export function defaultResolveBotRuntime(root = botsRoot()) {
+    if (!fs.existsSync(root))
+        return null;
+    const names = fs.readdirSync(root).sort();
+    const configs = names
+        .map((n) => {
+        try {
+            return readBotConfig(path.join(root, n));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((c) => c !== null);
+    const main = configs.find((c) => effectiveBotKind(c) === "personal") ?? null;
+    return main && isBotRuntimeId(main.runtime) ? main.runtime : null;
+}
+function yamlField(text, key) {
+    const m = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(text);
+    if (!m)
+        return "";
+    return m[1].replace(/\s+#.*$/, "").trim().replace(/^["']|["']$/g, "");
+}
+const REDO_ITEM_RE = /^sources\/([a-zA-Z0-9][a-zA-Z0-9._-]*)\/([^/.][^/]*\.md)$/;
+/**
+ * The channel of a `--redo` item, which must be written `sources/<channel>/<file>.md`,
+ * or null when it is not in that form.
+ */
+export function redoItemChannel(item) {
+    const m = REDO_ITEM_RE.exec(item);
+    return m && !m[2].includes("\0") ? m[1] : null;
+}
+/** Declared source channels with run: local (or any run: when forced). */
+export function listSourceChannels(hqRoot, company, force = false) {
+    const dir = path.join(hqRoot, "companies", company, "sources");
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!e.isDirectory())
+            continue;
+        const y = path.join(dir, e.name, "source.yaml");
+        if (!fs.existsSync(y))
+            continue;
+        const run = yamlField(fs.readFileSync(y, "utf8"), "run");
+        if (run === "local")
+            out.push({ channel: e.name, force: false });
+        else if (force)
+            out.push({ channel: e.name, force: true });
+    }
+    return out;
+}
+/** Shell single-quote a value so a generated script carries it as data. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** True when text has a control character, a double quote, $, a backtick or a backslash. */
+function hasUnsafeText(text) {
+    for (const ch of text) {
+        const code = ch.charCodeAt(0);
+        if (code < 0x20 || code === 0x7f || ch === '"' || ch === "`" || ch === "$" || ch === "\\")
+            return true;
+    }
+    return false;
+}
+const AUDIENCE_ENTRY = /^[A-Za-z0-9._%+@-]+$/;
+/**
+ * Refuse a worklist item whose path or audience could break out of the prompt
+ * or the channel folder. Returns the reason, or null when the item is safe.
+ */
+export function unsafeItemReason(item, channel) {
+    if (typeof item.file !== "string" || item.file === "")
+        return "no file";
+    const prefix = `sources/${channel}/`;
+    const name = item.file.slice(prefix.length);
+    if (!item.file.startsWith(prefix) || name === "" || name.includes("/") || name === "." || name === "..") {
+        return `file is not directly in sources/${channel}`;
+    }
+    if (hasUnsafeText(item.file))
+        return "file name has quote, $, backtick, backslash or control characters";
+    if (item.skip !== undefined)
+        return null;
+    if (!Array.isArray(item.audience) || item.audience.length === 0)
+        return "no audience";
+    for (const a of item.audience) {
+        if (typeof a !== "string" || !AUDIENCE_ENTRY.test(a))
+            return "audience entry is not an email, id or company";
+    }
+    if (item.audience_key !== undefined && !/^[A-Za-z0-9_-]+$/.test(item.audience_key))
+        return "bad audience_key";
+    return null;
+}
+export function buildExtractPrompt(input) {
+    const { item } = input;
+    const audience = (item.audience ?? []).join(",");
+    const ref = `${input.channel}:${path.basename(item.file)}`;
+    return [
+        "You are running the ontology worker's process-source skill unattended for ONE source item.",
+        "Follow the skill below, but only step 5 (Extract) for this single item. Do not build a worklist, do not mark the item done, do not run garden.",
+        "",
+        `COMPANY: ${input.company}`,
+        `CHANNEL: ${input.channel}`,
+        `ITEM: ${input.itemPath}`,
+        `AUDIENCE: ${audience}`,
+        `AUDIENCE_KEY: ${item.audience_key ?? ""}`,
+        `SOURCE_REF: ${ref}`,
+        "",
+        "Rules:",
+        input.runtime === "codex"
+            ? "- Read the item with a shell command such as cat. Only files in the item's channel folder are readable."
+            : "- Read the item with the Read tool. Only files in the item's channel folder are readable.",
+        `- Write candidates ONLY with: bash ${input.wrapperPath} --kind signal|entity --type <type> --body "<text>"`,
+        "- That command already fixes the company, audience and source ref for this item. Do not pass --company, --audience, --source-ref or --body-file; it refuses them.",
+        `- Signal types (exactly these): ${EXTRACT_SIGNAL_TYPES.join(", ")}.`,
+        `- Entity types: ${ENTITY_TYPES.join(", ")}.`,
+        "- Every signal body must end with a citation: a one-sentence quote from the item or its timestamp, for example: (cite: \"we ship Friday\") or (cite: 00:12:31).",
+        "- No other command can run, and no other file can be written.",
+        "- When finished, reply with one line: the number of candidates written.",
+        "",
+        "--- process-source skill ---",
+        input.skillText.trim(),
+    ].join("\n");
+}
+/**
+ * The per-item candidate command. It pins --company, --audience and
+ * --source-ref (a repeated flag must match the pinned value), refuses
+ * --body-file and any other flag, and calls ontology-candidate.sh write.
+ */
+export function buildCandidateWrapper(input) {
+    const script = path.join(input.hqRoot, "core", "scripts", "ontology-candidate.sh");
+    return [
+        "#!/usr/bin/env bash",
+        "# Generated by hq signals run (extract step) for one source item.",
+        "set -euo pipefail",
+        `PIN_COMPANY=${shellQuote(input.company)}`,
+        `PIN_AUDIENCE=${shellQuote(input.audience)}`,
+        `PIN_REF=${shellQuote(input.sourceRef)}`,
+        `HQ=${shellQuote(input.hqRoot)}`,
+        `SCRIPT=${shellQuote(script)}`,
+        'die() { echo "write-candidate: $*" >&2; exit 2; }',
+        'pinned() { [ "$2" = "$3" ] || die "$1 is fixed to $3 for this item"; }',
+        '[ "${1:-}" = "write" ] && shift',
+        'kind="" type="" body=""',
+        'while [ $# -gt 0 ]; do',
+        '  [ $# -ge 2 ] || die "$1 needs a value"',
+        '  case "$1" in',
+        '    --kind) kind="$2" ;;',
+        '    --type) type="$2" ;;',
+        '    --body) body="$2" ;;',
+        '    --company) pinned --company "$2" "$PIN_COMPANY" ;;',
+        '    --audience) pinned --audience "$2" "$PIN_AUDIENCE" ;;',
+        '    --source-ref) pinned --source-ref "$2" "$PIN_REF" ;;',
+        '    --body-file) die "--body-file is not allowed; pass the text with --body" ;;',
+        '    *) die "unknown flag $1 (allowed: --kind, --type, --body)" ;;',
+        '  esac',
+        '  shift 2',
+        'done',
+        'case "$kind" in signal|entity) ;; *) die "--kind must be signal or entity" ;; esac',
+        '[ -n "$type" ] || die "--type is required"',
+        '[ -n "$body" ] || die "--body is required"',
+        // Re-checked on every call, right before the write: the turn can create a
+        // link after the step's preflight, so a link anywhere on the candidate
+        // path (or a store folder that resolves elsewhere) stops the write.
+        'REAL_HQ="$(cd "$HQ" && pwd -P)"',
+        'for store in signals ontology; do',
+        '  rel="companies/$PIN_COMPANY/$store/_candidates"',
+        '  for p in "companies" "companies/$PIN_COMPANY" "companies/$PIN_COMPANY/$store" "$rel"; do',
+        '    [ -L "$HQ/$p" ] && die "refusing to write: $p is a link"',
+        '  done',
+        '  if [ -d "$HQ/$rel" ]; then',
+        '    [ "$(cd "$HQ/$rel" && pwd -P)" = "$REAL_HQ/$rel" ] || die "refusing to write: $rel resolves outside $PIN_COMPANY"',
+        '    [ -z "$(find "$HQ/$rel" -type l -print -quit)" ] || die "refusing to write: a link sits under $rel"',
+        '  fi',
+        'done',
+        'HQ_ROOT="$HQ" exec bash "$SCRIPT" write --company "$PIN_COMPANY" --kind "$kind" --type "$type" --audience "$PIN_AUDIENCE" --source-ref "$PIN_REF" --body "$body"',
+        "",
+    ].join("\n");
+}
+/** Parse a stream-json transcript (or a codex --json event stream). */
+export function parseTurnOutput(stdout) {
+    let result = null;
+    let codexTurns = 0;
+    let codexDone = false;
+    for (const line of stdout.split("\n")) {
+        const t = line.trim();
+        if (!t.startsWith("{"))
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(t);
+        }
+        catch {
+            continue;
+        }
+        if (!ev || typeof ev !== "object")
+            continue;
+        const o = ev;
+        if (o.type === "result")
+            result = o;
+        if (o.type === "turn.completed") {
+            codexTurns += 1;
+            codexDone = true;
+        }
+        if (o.type === "turn.failed")
+            codexTurns += 1;
+    }
+    if (result) {
+        const turns = typeof result.num_turns === "number" ? result.num_turns : 1;
+        const cost = typeof result.total_cost_usd === "number" ? result.total_cost_usd : typeof result.cost_usd === "number" ? result.cost_usd : 0;
+        return { result, turns, costUsd: cost };
+    }
+    if (codexTurns > 0) {
+        return { result: codexDone ? { type: "result", is_error: false } : { type: "result", is_error: true }, turns: codexTurns, costUsd: 0 };
+    }
+    return { result: null, turns: 0, costUsd: 0 };
+}
+function walkMd(dir, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        // Missing, or removed by a concurrent garden between listing and reading.
+        return;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory())
+            walkMd(p, out);
+        else if (e.name.endsWith(".md"))
+            out.add(p);
+    }
+}
+/** Every candidate file under every company's signals/ontology _candidates. */
+function allCandidateFiles(hqRoot) {
+    const out = new Set();
+    const companies = path.join(hqRoot, "companies");
+    if (!fs.existsSync(companies))
+        return out;
+    for (const e of fs.readdirSync(companies, { withFileTypes: true })) {
+        if (!e.isDirectory())
+            continue;
+        for (const store of ["signals", "ontology"])
+            walkMd(path.join(companies, e.name, store, "_candidates"), out);
+    }
+    return out;
+}
+function frontmatter(text) {
+    const m = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (!m)
+        return null;
+    const fm = {};
+    for (const line of m[1].split("\n")) {
+        const kv = /^([a-z_]+):\s*(.*)$/.exec(line);
+        if (kv)
+            fm[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, "");
+    }
+    return fm;
+}
+/** True when companies/<company>/sources/<channel>/<file> exists for a `<channel>:<file>` ref. */
+function companyHasSourceItem(hqRoot, company, sourceRef) {
+    const i = sourceRef.indexOf(":");
+    if (i <= 0)
+        return false;
+    const channel = sourceRef.slice(0, i);
+    const name = sourceRef.slice(i + 1);
+    if (!name || channel.includes("/") || name.includes("/") || channel === ".." || name === "..")
+        return false;
+    return fs.existsSync(path.join(hqRoot, "companies", company, "sources", channel, name));
+}
+/**
+ * Clean up the new candidate files a turn produced.
+ *
+ * With `scope`, only this item's files are touched: a file is this item's when
+ * its source_ref is the wrapper-pinned `scope.sourceRef`. Every other new file
+ * (another company's garden or extract, a /meeting-notes session, another
+ * source, garden moving a candidate into _done/) is left as it is and not
+ * counted.
+ * - In companies/<company>/: this item's file is kept when it conforms and
+ *   deleted when it does not.
+ * - In another company: this item's file is deleted and listed under `foreign`,
+ *   unless that company has its own source item with the same channel and file
+ *   name (then the file is that company's candidate, not a leak).
+ * Every delete goes through the company-scoped write guard.
+ */
+export function validateNewCandidates(files, expectedAudienceKey, scope) {
+    let kept = 0;
+    let rejected = 0;
+    const foreign = [];
+    for (const f of files) {
+        let text;
+        try {
+            text = fs.readFileSync(f, "utf8");
+        }
+        catch {
+            // Gone already (a concurrent garden moved it); nothing to clean up.
+            continue;
+        }
+        const fm = frontmatter(text);
+        // The path the file really lives at, every link followed. Ownership is
+        // decided on it: a file written through acme's linked type folder into
+        // beta's tree is beta's file, not acme's.
+        const realRel = realRelPath(scope.hqRoot, f);
+        if (fm?.source_ref !== scope.sourceRef)
+            continue;
+        const m = realRel === null ? null : /^companies\/([^/]+)\//.exec(realRel);
+        const fileCompany = m ? m[1] : null;
+        if (fileCompany !== scope.company) {
+            if (fileCompany !== null && companyHasSourceItem(scope.hqRoot, fileCompany, scope.sourceRef))
+                continue;
+            // Delete it in the company that really holds it, through the guard.
+            // A file that resolves outside every company folder is not deleted
+            // (fail closed); it is still reported and the item still fails.
+            if (realRel !== null && fileCompany !== null) {
+                try {
+                    guardedRemove(scope.hqRoot, realRel, { company: fileCompany });
+                }
+                catch {
+                    // Refused by the guard: leave it and report it below.
+                }
+            }
+            foreign.push(path.relative(scope.hqRoot, f));
+            rejected += 1;
+            continue;
+        }
+        const typeOk = fm !== null &&
+            ((fm.kind === "signal" && EXTRACT_SIGNAL_TYPES.includes(fm.type)) ||
+                (fm.kind === "entity" && ENTITY_TYPES.includes(fm.type)));
+        const ok = fm !== null &&
+            typeOk &&
+            Boolean(fm.source_ref) &&
+            Boolean(fm.audience_key) &&
+            (expectedAudienceKey === undefined || fm.audience_key === expectedAudienceKey);
+        if (ok)
+            kept += 1;
+        else {
+            if (realRel !== null) {
+                guardedRemove(scope.hqRoot, realRel, { company: scope.company });
+            }
+            rejected += 1;
+        }
+    }
+    return { kept, rejected, foreign };
+}
+function classifyFailure(text, fallback) {
+    if (CLAUDE_LOGGED_OUT_RE.test(text))
+        return { error: "coding tool is not logged in", errorKind: "signed-out" };
+    return { error: fallback, errorKind: "other" };
+}
+/** Absolute path of an executable as PATH resolves it, or null. */
+function resolveOnPath(bin, envPath) {
+    if (bin.includes("/"))
+        return fs.existsSync(bin) ? path.resolve(bin) : null;
+    for (const dir of (envPath ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const p = path.join(dir, bin);
+        try {
+            fs.accessSync(p, fs.constants.X_OK);
+            return p;
+        }
+        catch {
+            // not here
+        }
+    }
+    return null;
+}
+/**
+ * Install prefixes the sandboxed turn must read: codex's own (its sandbox
+ * helper re-executes it) and bash's (Homebrew bash loads its libraries from the
+ * prefix). For /opt/homebrew/bin/bash that is /opt/homebrew. A prefix that is
+ * /, the home directory, or overlaps the HQ root is never added.
+ */
+function toolPrefixRoots(bins, envPath, hqRoot) {
+    const hq = fs.realpathSync(hqRoot);
+    const home = os.homedir();
+    const overlaps = (a, b) => a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep);
+    const roots = [];
+    for (const bin of bins) {
+        const found = resolveOnPath(bin, envPath);
+        if (!found)
+            continue;
+        const forms = [found];
+        try {
+            forms.push(fs.realpathSync(found));
+        }
+        catch {
+            // dangling link: the spawn fails on its own
+        }
+        for (const f of forms) {
+            const prefix = path.dirname(path.dirname(f));
+            if (prefix === path.parse(prefix).root || prefix === home || overlaps(prefix, hq))
+                continue;
+            roots.push(prefix);
+        }
+    }
+    return [...new Set(roots)];
+}
+/** TOML inline table for the codex permission profile's filesystem entries. */
+export function codexFilesystemProfile(scope, codexBin, envPath) {
+    const entries = [[":minimal", "read"]];
+    for (const r of toolPrefixRoots([codexBin, "bash"], envPath, scope.hqRoot))
+        entries.push([r, "read"]);
+    entries.push([scope.turnDir, "read"]);
+    entries.push([path.join(fs.realpathSync(scope.hqRoot), "core", "scripts"), "read"]);
+    const prefs = path.join(fs.realpathSync(scope.hqRoot), "companies", scope.company, "settings", "knowledge");
+    if (fs.existsSync(prefs))
+        entries.push([prefs, "read"]);
+    const personalPrefs = path.join(fs.realpathSync(scope.hqRoot), "personal", "settings", "knowledge-preferences.yaml");
+    if (fs.existsSync(personalPrefs))
+        entries.push([personalPrefs, "read"]);
+    entries.push([scope.channelDir, "read"]);
+    for (const d of scope.candidateDirs)
+        entries.push([d, "write"]);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}=${JSON.stringify(v)}`).join(",")}}`;
+}
+export function claudeTurnArgs(prompt, scope, maxTurns, budgetUsd) {
+    return [
+        "-p",
+        prompt,
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--permission-mode",
+        "dontAsk",
+        "--permission-prompts",
+        "none",
+        "--restricted",
+        "--tools",
+        "Read,Bash",
+        "--strict-mcp-config",
+        "--mcp-config",
+        '{"mcpServers":{}}',
+        "--disable-slash-commands",
+        "--no-session-persistence",
+        "--max-turns",
+        String(maxTurns),
+        "--max-budget-usd",
+        budgetUsd.toFixed(4),
+        "--add-dir",
+        scope.channelDir,
+        "--allowedTools",
+        ...claudeAllowedTools(scope.channelDir, scope.wrapperPath),
+    ];
+}
+export function codexTurnArgs(prompt, scope, codexBin, envPath) {
+    const profile = CODEX_PERMISSION_PROFILE;
+    return [
+        "-a",
+        "never",
+        "exec",
+        "--json",
+        "--skip-git-repo-check",
+        "--ephemeral",
+        "--ignore-user-config",
+        "--ignore-rules",
+        "-C",
+        scope.turnDir,
+        "-c",
+        `default_permissions=${JSON.stringify(profile)}`,
+        "-c",
+        `permissions.${profile}.filesystem=${codexFilesystemProfile(scope, codexBin, envPath)}`,
+        "-c",
+        `permissions.${profile}.network.enabled=false`,
+        prompt,
+    ];
+}
+function runTurn(ctx, runtime, prompt, scope, budgetUsd, opts) {
+    const cwd = scope.turnDir;
+    const cmd = runtime === "claude" ? opts.claudeBin : opts.codexBin;
+    const args = runtime === "claude"
+        ? claudeTurnArgs(prompt, scope, ctx.maxTurns, budgetUsd)
+        : codexTurnArgs(prompt, scope, opts.codexBin, process.env.PATH);
+    const res = ctx.spawn(cmd, args, { cwd, env: { ...process.env, HQ_ROOT: ctx.hqRoot }, timeoutMs: opts.turnTimeoutMs });
+    const parsed = parseTurnOutput(res.stdout);
+    const all = `${res.stderr}\n${res.stdout}`;
+    if (res.error) {
+        const timedOut = /ETIMEDOUT|timed out/i.test(res.error.message) || res.error.code === "ETIMEDOUT";
+        if (timedOut)
+            return { ok: false, error: `${runtime} timed out after ${opts.turnTimeoutMs}ms`, errorKind: "transient", turns: parsed.turns, costUsd: parsed.costUsd };
+        return { ok: false, error: `${runtime} could not start: ${res.error.message}`.slice(0, 300), errorKind: "other", turns: 0, costUsd: 0 };
+    }
+    if (res.status !== 0) {
+        const c = classifyFailure(all, `${runtime} exited ${String(res.status)}: ${res.stderr.trim().slice(0, 200)}`);
+        return { ok: false, ...c, turns: parsed.turns, costUsd: parsed.costUsd };
+    }
+    if (!parsed.result)
+        return { ok: false, error: `${runtime} printed no result event`, errorKind: "other", turns: 0, costUsd: 0 };
+    if (parsed.result.is_error === true || (typeof parsed.result.subtype === "string" && parsed.result.subtype !== "success")) {
+        const text = typeof parsed.result.result === "string" ? parsed.result.result : String(parsed.result.subtype ?? "");
+        const c = classifyFailure(text, `${runtime} turn failed: ${text.slice(0, 200) || "error result"}`);
+        return { ok: false, ...c, turns: parsed.turns, costUsd: parsed.costUsd };
+    }
+    return { ok: true, turns: parsed.turns, costUsd: parsed.costUsd };
+}
+export function createExtractStep(options = {}) {
+    return {
+        name: "extract",
+        async run(ctx) {
+            const empty = { modelTurns: 0, estimatedSpendUsd: 0 };
+            const channels = listSourceChannels(ctx.hqRoot, ctx.company, options.force === true);
+            // A --redo item whose channel this step does not run cannot be re-queued here.
+            const unrunRedo = (ctx.redo ?? []).filter((f) => !channels.some((c) => c.channel === redoItemChannel(f)));
+            if (channels.length === 0 && unrunRedo.length === 0) {
+                return { status: "skipped", itemsIn: 0, itemsOut: 0, skippedReason: "no-sources", ...empty };
+            }
+            const runtime = (options.resolveBotRuntime ?? defaultResolveBotRuntime)() ?? options.runtime ?? "claude";
+            if (runtime === "grok") {
+                return {
+                    status: "failed",
+                    itemsIn: 0,
+                    itemsOut: 0,
+                    error: "grok has no restricted tool mode; extract needs claude or codex",
+                    errorKind: "other",
+                    ...empty,
+                };
+            }
+            const scripts = path.join(ctx.hqRoot, "core", "scripts");
+            const worklist = path.join(scripts, "ontology-source-worklist.sh");
+            const skillPath = path.join(ctx.hqRoot, "core", "workers", "public", "ontology", "skills", "process-source.md");
+            if (!fs.existsSync(worklist) || !fs.existsSync(skillPath)) {
+                return { status: "skipped", itemsIn: 0, itemsOut: 0, skippedReason: "ontology-worker-missing", ...empty };
+            }
+            const skillText = fs.readFileSync(skillPath, "utf8");
+            const turnOpts = {
+                claudeBin: options.claudeBin ?? "claude",
+                codexBin: options.codexBin ?? "codex",
+                turnTimeoutMs: options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS,
+            };
+            const env = { ...process.env, HQ_ROOT: ctx.hqRoot };
+            const limit = options.worklistLimit ?? DEFAULT_WORKLIST_LIMIT;
+            let itemsIn = 0;
+            let itemsOut = 0;
+            let modelTurns = 0;
+            let spent = 0;
+            let lastCost = 0;
+            let rejected = 0;
+            let processedAny = false;
+            let budgetStop = false;
+            let errorKind;
+            const failures = unrunRedo.map((file) => ({
+                file,
+                error: "redo: not a source channel this run processes (needs a source.yaml with run: local, or --force for run: cloud)",
+            }));
+            if (unrunRedo.length > 0)
+                errorKind = "other";
+            const skippedItems = [];
+            const sourcesReal = fs.realpathSync(path.join(ctx.hqRoot, "companies", ctx.company, "sources"));
+            outer: for (const ch of channels) {
+                const base = ["--company", ctx.company, "--channel", ch.channel, ...(ch.force ? ["--force"] : [])];
+                // The channel folder is the only place a turn may read. A symlink out of
+                // this company's sources/ would widen that, so refuse it.
+                const channelDir = fs.realpathSync(path.join(ctx.hqRoot, "companies", ctx.company, "sources", ch.channel));
+                if (!channelDir.startsWith(sourcesReal + path.sep)) {
+                    failures.push({ file: `sources/${ch.channel}`, error: "channel folder resolves outside this company's sources" });
+                    continue;
+                }
+                let candidateDirs = [];
+                // The candidate script writes into _candidates/<folder>/ with plain
+                // fs. A linked folder there that leads into another company's tree
+                // would land this item's candidates in that company, so refuse the
+                // channel before any turn runs (every runtime, not only codex).
+                try {
+                    for (const store of ["signals", "ontology"]) {
+                        assertNoEscapingLinks(ctx.hqRoot, `companies/${ctx.company}/${store}/_candidates`, { company: ctx.company });
+                    }
+                }
+                catch (e) {
+                    failures.push({ file: `sources/${ch.channel}`, error: `candidate folder refused: ${e.message}`.slice(0, 300) });
+                    if (!errorKind)
+                        errorKind = "other";
+                    continue;
+                }
+                if (runtime === "codex") {
+                    try {
+                        candidateDirs = ["signals", "ontology"].map((store) => {
+                            const dir = assertAllowedPath(ctx.hqRoot, `companies/${ctx.company}/${store}/_candidates`, { company: ctx.company });
+                            fs.mkdirSync(dir, { recursive: true });
+                            return fs.realpathSync(dir);
+                        });
+                    }
+                    catch (e) {
+                        failures.push({ file: `sources/${ch.channel}`, error: `candidate folder refused: ${e.message}`.slice(0, 300) });
+                        continue;
+                    }
+                }
+                // --redo: drop the named items from the worklist's ledgers so this listing includes them again.
+                const redo = (ctx.redo ?? []).filter((f) => redoItemChannel(f) === ch.channel);
+                if (redo.length > 0) {
+                    const rd = ctx.spawn("bash", [worklist, ...base, ...redo.flatMap((f) => ["--redo", f])], { cwd: ctx.hqRoot, env, timeoutMs: SCRIPT_TIMEOUT_MS });
+                    if (rd.error || rd.status !== 0) {
+                        failures.push({ file: `sources/${ch.channel}`, error: `redo failed: ${(rd.error?.message ?? rd.stderr.trim()).slice(0, 200) || `exit ${String(rd.status)}`}` });
+                        if (!errorKind)
+                            errorKind = "other";
+                        continue;
+                    }
+                }
+                const wl = ctx.spawn("bash", [worklist, ...base, "--limit", String(limit)], { cwd: ctx.hqRoot, env, timeoutMs: SCRIPT_TIMEOUT_MS });
+                if (wl.error || wl.status !== 0) {
+                    failures.push({ file: `sources/${ch.channel}`, error: `worklist failed: ${(wl.error?.message ?? wl.stderr.trim()).slice(0, 200) || `exit ${String(wl.status)}`}` });
+                    continue;
+                }
+                const items = [];
+                for (const line of wl.stdout.split("\n")) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        items.push(JSON.parse(line));
+                    }
+                    catch {
+                        failures.push({ file: `sources/${ch.channel}`, error: "worklist printed a non-JSON line" });
+                    }
+                }
+                for (const item of items) {
+                    itemsIn += 1;
+                    if (item.skip) {
+                        skippedItems.push({ file: String(item.file), reason: String(item.skip) });
+                        continue;
+                    }
+                    const unsafe = unsafeItemReason(item, ch.channel);
+                    if (unsafe) {
+                        failures.push({ file: String(item.file), error: `unsafe worklist item: ${unsafe}` });
+                        if (!errorKind)
+                            errorKind = "other";
+                        continue;
+                    }
+                    const remaining = ctx.maxBudgetUsd - spent;
+                    if (spent > 0 && (spent >= ctx.maxBudgetUsd || remaining < lastCost)) {
+                        budgetStop = true;
+                        break outer;
+                    }
+                    const sourceRef = `${ch.channel}:${path.basename(item.file)}`;
+                    const turnDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "hq-signals-extract-")));
+                    const wrapperPath = path.join(turnDir, CANDIDATE_WRAPPER_NAME);
+                    const before = allCandidateFiles(ctx.hqRoot);
+                    let turn;
+                    try {
+                        fs.writeFileSync(wrapperPath, buildCandidateWrapper({ hqRoot: ctx.hqRoot, company: ctx.company, audience: (item.audience ?? []).join(","), sourceRef }), { mode: 0o700 });
+                        const scope = { hqRoot: ctx.hqRoot, company: ctx.company, channelDir, turnDir, wrapperPath, candidateDirs };
+                        const prompt = buildExtractPrompt({
+                            skillText,
+                            company: ctx.company,
+                            channel: ch.channel,
+                            item,
+                            itemPath: path.join(channelDir, path.basename(item.file)),
+                            wrapperPath,
+                            runtime: runtime === "codex" ? "codex" : "claude",
+                        });
+                        turn = runTurn(ctx, runtime, prompt, scope, Math.max(0, remaining), turnOpts);
+                    }
+                    finally {
+                        fs.rmSync(turnDir, { recursive: true, force: true });
+                    }
+                    modelTurns += turn.turns;
+                    spent += turn.costUsd;
+                    lastCost = turn.costUsd;
+                    const created = [...allCandidateFiles(ctx.hqRoot)].filter((f) => !before.has(f));
+                    const v = validateNewCandidates(created, item.audience_key, { hqRoot: ctx.hqRoot, company: ctx.company, sourceRef });
+                    rejected += v.rejected;
+                    if (v.foreign.length > 0) {
+                        // Isolation breach: the files are already deleted; the item stays unprocessed.
+                        failures.push({ file: item.file, error: `candidate written outside ${ctx.company} (deleted): ${v.foreign.join(", ")}`.slice(0, 300) });
+                        if (!errorKind)
+                            errorKind = "other";
+                        continue;
+                    }
+                    if (!turn.ok) {
+                        failures.push({ file: item.file, error: turn.error ?? "turn failed" });
+                        if (turn.errorKind === "signed-out" || !errorKind)
+                            errorKind = turn.errorKind;
+                        if (turn.errorKind === "signed-out")
+                            break outer;
+                        continue;
+                    }
+                    itemsOut += v.kept;
+                    const md = ctx.spawn("bash", [worklist, ...base, "--mark-done", item.file], { cwd: ctx.hqRoot, env, timeoutMs: SCRIPT_TIMEOUT_MS });
+                    if (md.error || md.status !== 0) {
+                        failures.push({ file: item.file, error: `mark-done failed: ${md.stderr.trim().slice(0, 200)}` });
+                        continue;
+                    }
+                    processedAny = true;
+                }
+            }
+            const result = {
+                status: "ok",
+                itemsIn,
+                itemsOut,
+                modelTurns,
+                estimatedSpendUsd: Math.round(spent * 1e6) / 1e6,
+                ...(failures.length ? { failures } : {}),
+                ...(skippedItems.length ? { skippedItems } : {}),
+                ...(rejected ? { rejectedCandidates: rejected } : {}),
+            };
+            if (budgetStop) {
+                result.status = "partial";
+                result.error = "budget-exceeded";
+            }
+            else if (failures.length > 0) {
+                result.status = processedAny ? "partial" : "failed";
+                result.error = failures[0].error;
+                result.errorKind = errorKind ?? "other";
+            }
+            if (budgetStop && failures.length > 0)
+                result.errorKind = errorKind ?? "other";
+            return result;
+        },
+    };
+}
+export const extractStep = createExtractStep();
+//# sourceMappingURL=extract.js.map