@indigoai-us/hq-cli 5.345.193 → 5.345.194

package/dist/lib/hot-channels/signals-pass.js

@@ -1,9 +1,22 @@
 /**
- * The local signals pass (US-011). After a hot-channel run lands sources, the
- * pass takes the run's landed documents through the ontology worklist, asks
+ * The local signals pass (US-011). After each hot-channel adapter run, the
+ * pass takes the adapter's channel through the ontology worklist, asks
  * `claude -p` for signals one document at a time, and writes those signals to
  * `companies/{co}/signals/`. It returns the count for the run ledger.
  *
+ * Work comes from the worklist, not only from this run's landings: when the
+ * worklist script exits 0, the pass takes the channel's unprocessed items in
+ * the worklist's order (newest first) up to the run's document cap. Items the
+ * cap leaves over stay unmarked, and a later run picks them up, including a
+ * run that landed nothing (a bounded backlog drain: at most
+ * DEFAULT_MAX_SIGNAL_DOCS claude calls per run, and no claude call at all when
+ * the backlog is empty). A channel with no source.yaml (worklist exit 2, the
+ * usual case for a hot channel such as `meeting-events`) has no worklist, so
+ * the pass keeps its own backlog: landed documents it has not processed yet
+ * are listed in `sources/_signals-pending/{channel}.json` and drained, newest
+ * first by `when` (else `created_at`), on later runs under the same cap. A
+ * cloud-run source (exit 4) is skipped.
+ *
  * A landed document with both `payload_ref` and `raw_ref` is a pointer (the
  * meetings, Slack and Attio adapters land these). For it, claude gets the
  * pointer followed by the document `payload_ref` names, capped at
@@ -80,8 +93,6 @@ export const WORKLIST_TIMEOUT_MS = 60_000;
 export const DEFAULT_MAX_SIGNAL_DOCS = 20;
 /** Payload bytes sent to claude per document (200 KB). A longer payload is cut with a marker. */
 export const MAX_PAYLOAD_BYTES = 200 * 1024;
-/** Items the worklist lists per channel; landed documents must fall inside it. */
-const WORKLIST_LIMIT = 500;
 /** Output kept per child stream. A longer reply is bad output. */
 const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 /** Signals kept per document. */
@@ -173,7 +184,7 @@ export function defaultPromptFile() {
     return path.join(path.dirname(fileURLToPath(import.meta.url)), "prompts", "signals-pass.md");
 }
 export const CLAUDE_LOGGED_OUT_RE = /not logged in|log ?in|\/login|invalid api key|authenticat|oauth token/i;
-function channelOf(key) {
+export function channelOf(key) {
     const parts = key.split("/");
     if (parts.length !== 3 || parts[0] !== "sources" || !parts[2].endsWith(".md"))
         return null;
@@ -186,7 +197,69 @@ function channelOf(key) {
     }
     return parts[1];
 }
-function splitFrontmatter(text) {
+/**
+ * Vault-relative file that lists a channel's landed documents the pass has not
+ * processed yet. Only channels with no worklist (no source.yaml) use it.
+ */
+export function pendingSignalsKey(channel) {
+    assertSafeSegment(channel, "channel");
+    return `sources/_signals-pending/${channel}.json`;
+}
+/** The channel's pending landed keys; a missing or unreadable file is an empty backlog. */
+export async function readPendingSignals(vaultRoot, channel) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(path.join(vaultRoot, pendingSignalsKey(channel)), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.filter((key) => typeof key === "string" && channelOf(key) === channel);
+}
+/** Replace the channel's pending list; an empty list removes the file. */
+export async function writePendingSignals(vaultRoot, channel, keys, beforeWrite = async () => undefined) {
+    const file = path.join(vaultRoot, pendingSignalsKey(channel));
+    assertVaultPath(vaultRoot, file);
+    await beforeWrite();
+    if (keys.length === 0) {
+        await fs.rm(file, { force: true });
+        return;
+    }
+    await writeFileAtomic(vaultRoot, file, `${JSON.stringify([...new Set(keys)], null, 2)}\n`);
+}
+/** Add landed keys to the channel's pending list (kept once each). */
+export async function queuePendingSignals(vaultRoot, channel, keys, beforeWrite) {
+    for (const key of keys) {
+        if (channelOf(key) !== channel)
+            throw new Error(`${key} is not a document in sources/${channel}/`);
+    }
+    await writePendingSignals(vaultRoot, channel, [...(await readPendingSignals(vaultRoot, channel)), ...keys], beforeWrite);
+}
+/** When a landed document happened: `when`, else `created_at`; unknown sorts last. */
+export function landedDocTime(frontmatter) {
+    for (const field of ["when", "created_at"]) {
+        const value = frontmatter[field];
+        const text = value instanceof Date ? value.toISOString() : typeof value === "string" ? value : undefined;
+        if (text === undefined)
+            continue;
+        const ms = Date.parse(text);
+        if (!Number.isNaN(ms))
+            return ms;
+    }
+    return Number.NEGATIVE_INFINITY;
+}
+function isSafeChannel(channel) {
+    try {
+        assertSafeSegment(channel, "channel");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function splitFrontmatter(text) {
     const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
     if (!match)
         return { frontmatter: {}, body: text };
@@ -433,15 +506,19 @@ export function createClaudeSignalsPass(options) {
         cwd: options.hqRoot,
         env: { ...env, HQ_ROOT: options.hqRoot },
     });
-    /** Work items for the landed documents of one channel. */
-    const itemsFor = async (channel, files) => {
-        const wanted = new Set(files);
-        const run = await runWorklist(["--company", options.company, "--channel", channel, "--limit", String(WORKLIST_LIMIT)]);
+    /**
+     * Work items for one channel. With a worklist: its unprocessed items in its
+     * order (at most `limit`). Without one: this run's landed `files` plus the
+     * channel's pending backlog, newest first, all of them (`pending` is set and
+     * the caller applies the cap).
+     */
+    const itemsFor = async (channel, files, limit) => {
+        const run = await runWorklist(["--company", options.company, "--channel", channel, "--limit", String(limit)]);
         if (run.timedOut)
             throw new Error(`ontology worklist timed out for channel ${channel}`);
         // Exit 4: the source is assigned to the cloud agent. Its documents are not this pass's to process.
         if (run.code === 4)
-            return [];
+            return { items: [], pending: false };
         if (run.code === 0) {
             const items = [];
             for (const line of run.stdout.split("\n")) {
@@ -454,7 +531,7 @@ export function createClaudeSignalsPass(options) {
                 catch {
                     continue;
                 }
-                if (typeof row.file !== "string" || !wanted.has(row.file) || row.skip !== undefined)
+                if (typeof row.file !== "string" || channelOf(row.file) !== channel || row.skip !== undefined)
                     continue;
                 if (typeof row.audience_key !== "string" || !Array.isArray(row.audience))
                     continue;
@@ -467,30 +544,46 @@ export function createClaudeSignalsPass(options) {
                     fromWorklist: true,
                 });
             }
-            return items;
+            return { items, pending: false };
         }
         // Any other exit (usually 2: the channel has no source.yaml yet, which is
         // normal for a hot channel) falls back to the landed document's own
-        // audience frontmatter, which landing always writes.
-        const items = [];
-        for (const file of files) {
-            const { frontmatter } = splitFrontmatter(await fs.readFile(path.join(vaultRoot, file), "utf8"));
+        // audience frontmatter, which landing always writes. The pass's own
+        // pending backlog stands in for the worklist.
+        const candidates = [...new Set([...files, ...(await readPendingSignals(vaultRoot, channel))])];
+        const dated = [];
+        for (const file of candidates) {
+            let text;
+            try {
+                text = await fs.readFile(path.join(vaultRoot, file), "utf8");
+            }
+            catch (err) {
+                // A pending document that is gone has nothing left to process.
+                if (isMissing(err))
+                    continue;
+                throw err;
+            }
+            const { frontmatter } = splitFrontmatter(text);
             const audience = Array.isArray(frontmatter.audience)
                 ? frontmatter.audience.filter((a) => typeof a === "string" && a.trim().length > 0)
                 : [];
             // No audience: skipped, never widened to company.
             if (audience.length === 0)
                 continue;
-            items.push({
-                file,
-                channel,
-                principals: audience,
-                audienceKey: audienceKey(audience),
-                audienceSource: typeof frontmatter.audience_source === "string" ? frontmatter.audience_source : "frontmatter",
-                fromWorklist: false,
+            dated.push({
+                item: {
+                    file,
+                    channel,
+                    principals: audience,
+                    audienceKey: audienceKey(audience),
+                    audienceSource: typeof frontmatter.audience_source === "string" ? frontmatter.audience_source : "frontmatter",
+                    fromWorklist: false,
+                },
+                at: landedDocTime(frontmatter),
             });
         }
-        return items;
+        dated.sort((a, b) => b.at - a.at || (a.item.file < b.item.file ? -1 : a.item.file > b.item.file ? 1 : 0));
+        return { items: dated.map((d) => d.item), pending: true };
     };
     const extract = async (item, input) => {
         prompt ??= fs.readFile(promptFile, "utf8");
@@ -549,23 +642,35 @@ export function createClaudeSignalsPass(options) {
     return async (result, guard) => {
         const beforeWrite = guard?.beforeWrite ?? (async () => undefined);
         const byChannel = new Map();
+        // The adapter's own channel is listed even when this run landed nothing
+        // there, so items an earlier run left over the cap still get processed.
+        if (result.channel !== undefined && isSafeChannel(result.channel))
+            byChannel.set(result.channel, []);
         for (const key of result.landedKeys ?? []) {
             const channel = channelOf(key);
             if (!channel)
                 continue;
             byChannel.set(channel, [...(byChannel.get(channel) ?? []), key]);
         }
-        // Nothing landed: there is no pass to run, so claude is not called.
-        if (byChannel.size === 0)
-            return 0;
-        preflight ??= checkLogin();
-        await preflight;
         let total = 0;
         for (const [channel, files] of byChannel) {
-            for (const item of await itemsFor(channel, files)) {
-                // Documents over the cap stay unmarked in the worklist for a later pass.
+            // With the cap spent and nothing landed here, there is nothing to list:
+            // the channel's backlog stays where it is (worklist or pending file).
+            if (docsSent >= maxDocs && files.length === 0)
+                continue;
+            const work = await itemsFor(channel, files, Math.max(0, maxDocs - docsSent));
+            // No worklist: every candidate is pending until it is processed, so
+            // documents over the cap (or left by a failed call) wait for a later run.
+            let pending = work.pending ? work.items.map((item) => item.file) : undefined;
+            if (pending !== undefined)
+                await writePendingSignals(vaultRoot, channel, pending, beforeWrite);
+            for (const item of work.items) {
+                // Documents over the cap stay in the worklist or the pending file for a later run.
                 if (docsSent >= maxDocs)
-                    return total;
+                    break;
+                // Log in once per run, and only when there is a document to send.
+                preflight ??= checkLogin();
+                await preflight;
                 docsSent += 1;
                 const input = await buildSignalsInput(vaultRoot, item.file);
                 if (input.fallback !== undefined) {
@@ -575,6 +680,10 @@ export function createClaudeSignalsPass(options) {
                 if (item.fromWorklist) {
                     await runWorklist(["--company", options.company, "--channel", channel, "--mark-done", item.file]);
                 }
+                else if (pending !== undefined) {
+                    pending = pending.filter((file) => file !== item.file);
+                    await writePendingSignals(vaultRoot, channel, pending, beforeWrite);
+                }
             }
         }
         return total;

package/dist/lib/hot-channels/signals-redo.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Queue landed hot-channel documents for the local signals pass again, and
+ * run the pass now (`hq sources signals`). Used when a run's documents never
+ * got signals: for example, the 20-document cap of an older build, or a pass
+ * that failed. A sync cursor never offers those documents again, so this is
+ * the way to reach them.
+ *
+ * Where a document is queued depends on its channel:
+ *   - no source.yaml (the usual hot channel, such as `meeting-events`): the
+ *     pass's own pending file, `sources/_signals-pending/{channel}.json`;
+ *   - a source.yaml: the ontology worklist's `--redo`, which drops the item
+ *     from the worklist's ledgers so the next listing includes it.
+ */
+import type { HotChannelRunResult } from "./loop.js";
+/** Bad input (key, channel or date): the command exits 2. */
+export declare class SignalsRedoUsageError extends Error {
+    constructor(message: string);
+}
+export interface SignalsRedoSelection {
+    /** Channels with no source.yaml: keys for the pass's pending file. */
+    pending: Map<string, string[]>;
+    /** Channels with a source.yaml: keys for the worklist's `--redo`. */
+    worklist: Map<string, string[]>;
+    notices: string[];
+}
+export interface SelectSignalsRedoInput {
+    vaultRoot: string;
+    /** Landed keys (`sources/{channel}/{id}.md`) to process again, signals or not. */
+    keys?: readonly string[];
+    /** Landed documents whose `when` (else `created_at`) is at or after this, with no signals yet. */
+    since?: Date;
+    /** Limit `since` to one channel. */
+    channel?: string;
+}
+/**
+ * Parse `--since`: a bare `YYYY-MM-DD` is local midnight, so a day's meetings
+ * are the ones in the machine's own time zone. Anything else must be an ISO
+ * date-time.
+ */
+export declare function parseSince(value: string): Date;
+/** Every `source_ref` in the company's signal index (`signals/_index/*.json`). */
+export declare function signalledSourceRefs(vaultRoot: string): Promise<Set<string>>;
+/** Which landed documents to process again, grouped by how each is queued. */
+export declare function selectSignalsRedo(input: SelectSignalsRedoInput): Promise<SignalsRedoSelection>;
+/**
+ * Queue the selection: pending keys into the pass's pending file, worklist
+ * keys through `ontology-source-worklist.sh --redo`. Throws when the worklist
+ * refuses (an older script has no `--redo`).
+ */
+export declare function queueSignalsRedo(input: {
+    hqRoot: string;
+    company: string;
+    selection: SignalsRedoSelection;
+    beforeWrite?: () => Promise<void>;
+    worklistScript?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<void>;
+/** A run result with nothing landed, so the signals pass works through one channel's backlog. */
+export declare function backlogRunResult(channel: string): HotChannelRunResult;
+//# sourceMappingURL=signals-redo.d.ts.map

package/dist/lib/hot-channels/signals-redo.js

@@ -0,0 +1,207 @@
+/**
+ * Queue landed hot-channel documents for the local signals pass again, and
+ * run the pass now (`hq sources signals`). Used when a run's documents never
+ * got signals: for example, the 20-document cap of an older build, or a pass
+ * that failed. A sync cursor never offers those documents again, so this is
+ * the way to reach them.
+ *
+ * Where a document is queued depends on its channel:
+ *   - no source.yaml (the usual hot channel, such as `meeting-events`): the
+ *     pass's own pending file, `sources/_signals-pending/{channel}.json`;
+ *   - a source.yaml: the ontology worklist's `--redo`, which drops the item
+ *     from the worklist's ledgers so the next listing includes it.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { assertSafeSegment } from "./landing.js";
+import { channelOf, landedDocTime, queuePendingSignals, runBounded, splitFrontmatter, WORKLIST_TIMEOUT_MS, } from "./signals-pass.js";
+/** Bad input (key, channel or date): the command exits 2. */
+export class SignalsRedoUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SignalsRedoUsageError";
+    }
+}
+/**
+ * Parse `--since`: a bare `YYYY-MM-DD` is local midnight, so a day's meetings
+ * are the ones in the machine's own time zone. Anything else must be an ISO
+ * date-time.
+ */
+export function parseSince(value) {
+    const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    const date = day ? new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3])) : new Date(Date.parse(value));
+    if (Number.isNaN(date.getTime()))
+        throw new SignalsRedoUsageError(`--since must be YYYY-MM-DD or an ISO date-time: ${value}`);
+    return date;
+}
+async function hasSourceYaml(vaultRoot, channel) {
+    try {
+        return (await fs.stat(path.join(vaultRoot, "sources", channel, "source.yaml"))).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isFile(file) {
+    try {
+        return (await fs.stat(file)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Every `source_ref` in the company's signal index (`signals/_index/*.json`). */
+export async function signalledSourceRefs(vaultRoot) {
+    const dir = path.join(vaultRoot, "signals", "_index");
+    const refs = new Set();
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return refs;
+    }
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const rows = JSON.parse(await fs.readFile(path.join(dir, name), "utf8"));
+            if (!Array.isArray(rows))
+                continue;
+            for (const row of rows) {
+                const ref = row?.source_ref;
+                if (typeof ref === "string")
+                    refs.add(ref);
+            }
+        }
+        catch {
+            // An unreadable index day says nothing about which sources have signals.
+        }
+    }
+    return refs;
+}
+function add(map, channel, key) {
+    const list = map.get(channel) ?? [];
+    if (!list.includes(key))
+        list.push(key);
+    map.set(channel, list);
+}
+/** Which landed documents to process again, grouped by how each is queued. */
+export async function selectSignalsRedo(input) {
+    const { vaultRoot } = input;
+    const selection = { pending: new Map(), worklist: new Map(), notices: [] };
+    if (input.channel !== undefined) {
+        try {
+            assertSafeSegment(input.channel, "channel");
+        }
+        catch {
+            throw new SignalsRedoUsageError(`not a channel name: ${input.channel}`);
+        }
+    }
+    const worklistChannel = new Map();
+    const usesWorklist = async (channel) => {
+        if (!worklistChannel.has(channel))
+            worklistChannel.set(channel, await hasSourceYaml(vaultRoot, channel));
+        return worklistChannel.get(channel) === true;
+    };
+    for (const key of input.keys ?? []) {
+        const channel = channelOf(key);
+        if (!channel || channel.startsWith("_"))
+            throw new SignalsRedoUsageError(`--key must be sources/<channel>/<id>.md: ${key}`);
+        if (!(await isFile(path.join(vaultRoot, key))))
+            throw new SignalsRedoUsageError(`no landed document at ${key}`);
+        add((await usesWorklist(channel)) ? selection.worklist : selection.pending, channel, key);
+    }
+    if (input.since !== undefined) {
+        const since = input.since.getTime();
+        const signalled = await signalledSourceRefs(vaultRoot);
+        let channels;
+        if (input.channel !== undefined) {
+            channels = [input.channel];
+        }
+        else {
+            try {
+                const entries = await fs.readdir(path.join(vaultRoot, "sources"), { withFileTypes: true });
+                channels = entries
+                    .filter((e) => e.isDirectory() && !e.name.startsWith("_") && !e.name.startsWith("."))
+                    .map((e) => e.name)
+                    .sort();
+            }
+            catch {
+                channels = [];
+            }
+        }
+        const withWorklist = [];
+        for (const channel of channels) {
+            if (await usesWorklist(channel)) {
+                // The worklist already lists its channel's unprocessed items, and the pass drains them.
+                withWorklist.push(channel);
+                continue;
+            }
+            let names;
+            try {
+                names = (await fs.readdir(path.join(vaultRoot, "sources", channel))).filter((n) => n.endsWith(".md")).sort();
+            }
+            catch {
+                continue;
+            }
+            for (const name of names) {
+                const key = `sources/${channel}/${name}`;
+                if (channelOf(key) !== channel || signalled.has(key))
+                    continue;
+                let text;
+                try {
+                    text = await fs.readFile(path.join(vaultRoot, key), "utf8");
+                }
+                catch {
+                    continue;
+                }
+                if (landedDocTime(splitFrontmatter(text).frontmatter) >= since)
+                    add(selection.pending, channel, key);
+            }
+        }
+        if (withWorklist.length > 0) {
+            selection.notices.push(`Skipped for --since (their worklist lists unprocessed items itself; use --key to redo one): ${withWorklist.join(", ")}`);
+        }
+    }
+    return selection;
+}
+/**
+ * Queue the selection: pending keys into the pass's pending file, worklist
+ * keys through `ontology-source-worklist.sh --redo`. Throws when the worklist
+ * refuses (an older script has no `--redo`).
+ */
+export async function queueSignalsRedo(input) {
+    const vaultRoot = path.join(input.hqRoot, "companies", input.company);
+    for (const [channel, keys] of input.selection.pending) {
+        await queuePendingSignals(vaultRoot, channel, keys, input.beforeWrite);
+    }
+    const worklist = input.worklistScript ?? path.join(input.hqRoot, "core", "scripts", "ontology-source-worklist.sh");
+    for (const [channel, keys] of input.selection.worklist) {
+        await input.beforeWrite?.();
+        const run = await runBounded("bash", [worklist, "--company", input.company, "--channel", channel, ...keys.flatMap((key) => ["--redo", key])], { timeoutMs: WORKLIST_TIMEOUT_MS, cwd: input.hqRoot, env: { ...(input.env ?? process.env), HQ_ROOT: input.hqRoot } });
+        if (run.timedOut || run.code !== 0) {
+            const why = run.timedOut ? "timed out" : run.stderr.trim().slice(0, 200) || `exit ${String(run.code)}`;
+            throw new Error(`ontology worklist --redo failed for sources/${channel}: ${why}`);
+        }
+    }
+}
+/** A run result with nothing landed, so the signals pass works through one channel's backlog. */
+export function backlogRunResult(channel) {
+    return {
+        adapterId: "signals-redo",
+        provider: "signals-redo",
+        channel,
+        connectionId: null,
+        transport: null,
+        landed: 0,
+        duplicates: 0,
+        stale: 0,
+        rejected: 0,
+        pages: 0,
+        landedKeys: [],
+        cursorBefore: null,
+        cursorAfter: null,
+    };
+}
+//# sourceMappingURL=signals-redo.js.map

package/dist/lib/signals/engine.d.ts

@@ -161,6 +161,12 @@ export interface RunSignalsOptions {
     signalsAlert?: SignalsRunAlertSenders;
     /** Lock liveness check; defaults to process.kill(pid, 0). */
     isPidAlive?: (pid: number) => boolean;
+    /**
+     * Source items (`sources/<channel>/<file>.md`) to process again: the extract
+     * step re-queues each with the worklist's `--redo` before listing its
+     * channel. Needs `company`.
+     */
+    redo?: readonly string[];
 }
 /** Bad input from the caller (company slug, missing company): exit 2. */
 export declare class SignalsUsageError extends Error {

package/dist/lib/signals/engine.js

@@ -18,7 +18,7 @@ import { guardedWrite, WriteGuardError } from "./write-guard.js";
 import { acquireCompanyLock, withSummaryLock } from "./run-lock.js";
 import { gardenStep } from "./steps/garden.js";
 import { adaptersStep } from "./steps/adapters.js";
-import { extractStep } from "./steps/extract.js";
+import { extractStep, redoItemChannel } from "./steps/extract.js";
 import { uploadStep } from "./steps/upload.js";
 import { raiseSignalsRunAlerts } from "./failure-alert.js";
 export const SIGNALS_TRIGGERS = ["job", "chat", "manual", "brief"];
@@ -255,6 +255,14 @@ export async function runSignals(opts) {
     if (opts.company !== undefined && !fs.existsSync(path.join(hqRoot, "companies", opts.company))) {
         throw new SignalsUsageError(`no company directory: companies/${opts.company}`);
     }
+    const redo = opts.redo ?? [];
+    if (redo.length > 0) {
+        if (opts.company === undefined)
+            throw new SignalsUsageError("--redo needs --company");
+        const bad = redo.find((f) => redoItemChannel(f) === null);
+        if (bad !== undefined)
+            throw new SignalsUsageError(`--redo item must be sources/<channel>/<file>.md: ${bad}`);
+    }
     const companies = opts.company !== undefined ? [opts.company] : listCompanies(hqRoot);
     const start = now();
     const date = localDate(start);
@@ -397,6 +405,7 @@ export async function runSignals(opts) {
                     ...(opts.uploadDeps ? { uploadDeps: opts.uploadDeps } : {}),
                     ...(opts.isFlagOn ? { isFlagOn: opts.isFlagOn } : {}),
                     ...(opts.registeredAdapterIds ? { registeredAdapterIds: opts.registeredAdapterIds } : {}),
+                    ...(redo.length > 0 ? { redo } : {}),
                 };
                 let stepRec;
                 const planner = stepImpls[name].dryRun;

package/dist/lib/signals/steps/extract.d.ts

@@ -31,6 +31,11 @@ interface WorkItem {
 }
 /** First personal bot under ~/.hq/bots (by name) with a readable config. */
 export declare function defaultResolveBotRuntime(root?: string): BotRuntimeId | null;
+/**
+ * The channel of a `--redo` item, which must be written `sources/<channel>/<file>.md`,
+ * or null when it is not in that form.
+ */
+export declare function redoItemChannel(item: string): string | null;
 /** Declared source channels with run: local (or any run: when forced). */
 export declare function listSourceChannels(hqRoot: string, company: string, force?: boolean): SourceChannel[];
 /** Shell single-quote a value so a generated script carries it as data. */

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

@@ -104,6 +104,15 @@ function yamlField(text, key) {
         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");
@@ -573,8 +582,11 @@ export function createExtractStep(options = {}) {
         async run(ctx) {
             const empty = { modelTurns: 0, estimatedSpendUsd: 0 };
             const channels = listSourceChannels(ctx.hqRoot, ctx.company, options.force === true);
-            if (channels.length === 0)
+            // 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 {
@@ -609,7 +621,12 @@ export function createExtractStep(options = {}) {
             let processedAny = false;
             let budgetStop = false;
             let errorKind;
-            const failures = [];
+            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) {
@@ -650,6 +667,17 @@ export function createExtractStep(options = {}) {
                         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)}`}` });

package/dist/lib/signals/steps/types.d.ts

@@ -56,6 +56,11 @@ export interface StepContext {
      * evaluator with the signed-in session.
      */
     isFlagOn?: AdapterFlagReader;
+    /**
+     * Source items (`sources/<channel>/<file>.md`) the extract step re-queues
+     * with the worklist's `--redo` before it lists that channel.
+     */
+    redo?: readonly string[];
 }
 export interface StepResult {
     status: StepStatus;