@indigoai-us/hq-cli 5.345.143 → 5.345.145

package/dist/commands/core-checkpoint-native.js

@@ -92,6 +92,14 @@ const SIBLING_LOCK_TTL_MS = 60 * 60 * 1000;
 export const SIBLING_MAX_RUNTIME_MS = 30 * 60 * 1000;
 /** Newest-wins cap so a wedged sibling cannot grow an unbounded queue. */
 const MAX_PENDING_PAYLOADS = 50;
+/**
+ * Queued payloads one sibling run may process, across its launch claim and its
+ * own queue drain. Each one runs the full upgrade flow, so a 50-deep queue in
+ * one run outlasts SIBLING_MAX_RUNTIME_MS and the grok turn cap; the run is
+ * then killed with work half done. The launcher re-queues the overflow for the
+ * next sibling instead.
+ */
+export const MAX_QUEUED_PAYLOADS_PER_RUN = 5;
 class CheckpointUsageError extends Error {
 }
 /**
@@ -202,16 +210,37 @@ report instead of guessing.
    skip silently on any failure. Hook or automation improvements go ONLY under
    personal/hooks/ as proposals.
 7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.
-8. Write <runDir>/report.md — full prose: what you read, what you changed
-   (paths), and what you skipped and why. List every policy or knowledge file
-   you amended, superseded, merged or deleted with the reason, so a human can
+8. Write <runDir>/report.md NOW, before you touch any queued payload — full
+   prose: what you read, what you changed (paths), and what you skipped and
+   why. List every policy or knowledge file you
+   amended, superseded, merged or deleted with the reason, so a human can
    audit and reverse it; a deletion you do not name in the report is a defect.
-   Then drain the queue: while
-   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim
+   The run can be stopped at its time or turn cap at any point after this, so
+   this run's own report must already exist.
+9. QUEUED PAYLOADS CLAIMED AT LAUNCH: the payload's pending_payloads array
+   holds checkpoints that were queued while an earlier sibling was busy; the
+   same records are in <runDir>/pending-claimed.jsonl. The launcher hands one
+   run at most <maxQueued> of them and has already put any others back in
+   workspace/checkpoints/sibling/pending.jsonl. For EACH record in
+   pending_payloads, in order, run steps 1-5 with that record as the payload:
+   upgrade the thread file named in its thread_path IN PLACE and drop -auto-
+   from its filename. If that -auto- file no longer exists, the record was
+   already processed; note it and move on. For a queued record, skip the
+   journal close in step 4 (it belongs to the parent session) and skip step 5b
+   (ontology); in steps 3 and 7, <company> means that record's own company, not
+   this run's. After EACH record, append one line to <runDir>/report.md naming
+   its thread and what you did, so a run stopped mid-queue shows how far it got.
+   If the array is empty, skip this step.
+10. Drain the queue, still within the same limit of <maxQueued> queued records
+   per run counted across step 9 and this step: while
+   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty and you
+   have processed fewer than <maxQueued> queued records, claim
    it atomically by renaming it aside —
    mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl
-   (N counting up from 2) — and process the claimed payloads with this same
-   flow. Repeat until a claim finds nothing left, then update the report.
+   (N counting up from 2) — and process its records as in step 9. When you
+   reach the limit, append every record of that claimed file you did not
+   process back to workspace/checkpoints/sibling/pending.jsonl (append with >>,
+   never overwrite) so the next sibling takes it, and record that in the report.
    NEVER read the queue and truncate it in place: a payload appended between
    your read and the truncate is lost, and its checkpoint is never enriched.
 `;
@@ -241,7 +270,8 @@ export function renderSiblingPrompt(runDir, payloadPath, options = {}) {
         .replaceAll("<ontologyStep>", () => ontologyStep)
         .replaceAll("<runDir>", () => runDir)
         .replaceAll("<payloadPath>", () => payloadPath)
-        .replaceAll("<hqRoot>", () => options.hqRoot ?? "");
+        .replaceAll("<hqRoot>", () => options.hqRoot ?? "")
+        .replaceAll("<maxQueued>", () => String(MAX_QUEUED_PAYLOADS_PER_RUN));
 }
 function collect(value, previous) {
     return [...previous, value];
@@ -1137,7 +1167,8 @@ function appendPending(pendingPath, payload) {
  * describes is never enriched. Renaming is atomic, so this run receives exactly
  * the file that existed at the moment of the claim while concurrent callers go
  * on appending to a fresh queue. The claimed file is left in the run directory
- * as an audit trail and as a recovery point if this sibling dies.
+ * as an audit trail and as a recovery point if this sibling dies: the next
+ * launch re-queues its unprocessed records through recoverOrphanedClaims.
  */
 function claimPending(pendingPath, claimPath) {
     try {
@@ -1162,6 +1193,124 @@ function claimPending(pendingPath, claimPath) {
     }
     return entries;
 }
+/**
+ * Keep the oldest {@link MAX_QUEUED_PAYLOADS_PER_RUN} claimed payloads for this
+ * run and append the rest back to the queue, so a deep queue is worked off
+ * across several runs instead of being lost when one run hits its cap. The
+ * claim file is rewritten to hold only what this run owns.
+ */
+export function limitClaimedPayloads(entries, claimPath, pendingPath, limit = MAX_QUEUED_PAYLOADS_PER_RUN) {
+    if (entries.length <= limit)
+        return entries;
+    const kept = entries.slice(0, limit);
+    const overflow = entries.slice(limit);
+    // Re-queue first: if the rewrite below fails, every record is still on disk.
+    fs.appendFileSync(pendingPath, overflow.map((entry) => `${JSON.stringify(entry)}\n`).join(""));
+    fs.writeFileSync(claimPath, kept.map((entry) => `${JSON.stringify(entry)}\n`).join(""));
+    return kept;
+}
+/** Times one queued record may be recovered from a finished run before it is dropped. */
+export const MAX_CLAIM_RECOVERIES = 3;
+/**
+ * Put back the queued records a finished sibling claimed but never processed.
+ *
+ * A sibling stopped at its wall-clock or turn cap leaves its claim files
+ * (pending-claimed*.jsonl) in its run directory. A record whose thread file
+ * still exists at its thread_path was not upgraded (the sibling renames the
+ * -auto- file when it is done), so it is appended back to pending.jsonl for
+ * this launch to claim. Only runs whose process is gone are read, records
+ * already queued are not duplicated, and each record is recovered at most
+ * {@link MAX_CLAIM_RECOVERIES} times so one the sibling keeps skipping cannot
+ * cycle forever. Each claim file read is renamed to *.recovered.
+ */
+export function recoverOrphanedClaims(siblingRoot, pendingPath, liveRoot) {
+    let runDirs;
+    try {
+        runDirs = fs.readdirSync(siblingRoot).filter((entry) => entry !== "pending.jsonl");
+    }
+    catch {
+        return 0;
+    }
+    const queuedThreads = new Set();
+    try {
+        for (const line of fs.readFileSync(pendingPath, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const threadPath = JSON.parse(line).thread_path;
+                if (typeof threadPath === "string")
+                    queuedThreads.add(threadPath);
+            }
+            catch {
+                // A torn line names no thread.
+            }
+        }
+    }
+    catch {
+        // No queue yet.
+    }
+    const recovered = [];
+    let count = 0;
+    for (const runDir of runDirs.sort()) {
+        const absolute = path.join(siblingRoot, runDir);
+        let claimFiles;
+        try {
+            claimFiles = fs.readdirSync(absolute).filter((entry) => /^pending-claimed(?:-\d+)?\.jsonl$/u.test(entry));
+        }
+        catch {
+            continue;
+        }
+        if (claimFiles.length === 0)
+            continue;
+        let pid = Number.NaN;
+        try {
+            pid = Number.parseInt(fs.readFileSync(path.join(absolute, "sibling.pid"), "utf8").trim(), 10);
+        }
+        catch {
+            // A run that never recorded a PID cannot still be running.
+        }
+        if (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))
+            continue;
+        for (const claimFile of claimFiles.sort()) {
+            const claimPath = path.join(absolute, claimFile);
+            let content;
+            try {
+                content = fs.readFileSync(claimPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            for (const line of content.split("\n")) {
+                if (!line.trim())
+                    continue;
+                let entry;
+                try {
+                    entry = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const threadPath = entry.thread_path;
+                if (typeof threadPath !== "string" || !threadPath || queuedThreads.has(threadPath))
+                    continue;
+                if (!fs.existsSync(path.resolve(liveRoot, threadPath)))
+                    continue;
+                const attempts = typeof entry.claim_recoveries === "number" ? entry.claim_recoveries : 0;
+                if (attempts >= MAX_CLAIM_RECOVERIES)
+                    continue;
+                queuedThreads.add(threadPath);
+                recovered.push(`${JSON.stringify({ ...entry, claim_recoveries: attempts + 1 })}\n`);
+                count += 1;
+            }
+            // Re-queue before retiring the claim file, so a failure leaves the
+            // records on disk; a repeat read is deduplicated by thread_path above.
+            if (recovered.length > 0)
+                fs.appendFileSync(pendingPath, recovered.splice(0).join(""));
+            fs.renameSync(claimPath, `${claimPath}.recovered`);
+        }
+    }
+    return count;
+}
 async function startSibling(liveRoot, input, threadPath, backend) {
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
     const siblingRoot = path.join(liveRoot, "workspace", "checkpoints", "sibling");
@@ -1183,9 +1332,17 @@ async function startSibling(liveRoot, input, threadPath, backend) {
         printResult(`checkpoint: sibling busy — payload queued (${depth} pending)`);
         return;
     }
+    // Before this run's directory exists, so only earlier runs are read.
+    try {
+        recoverOrphanedClaims(siblingRoot, pendingPath, liveRoot);
+    }
+    catch {
+        // Recovery is best effort; the claim files stay on disk for the next launch.
+    }
     const runDir = path.join(siblingRoot, `${formatTimestamp(new Date())}-${summarySlug(input.summary ?? "checkpoint")}`);
     fs.mkdirSync(runDir, { recursive: true });
-    payload.pending_payloads = claimPending(pendingPath, path.join(runDir, "pending-claimed.jsonl"));
+    const claimPath = path.join(runDir, "pending-claimed.jsonl");
+    payload.pending_payloads = limitClaimedPayloads(claimPending(pendingPath, claimPath), claimPath, pendingPath);
     if (!payload.company) {
         let queued;
         try {

package/dist/commands/core-job-notify-native.js

@@ -195,6 +195,40 @@ function emailFromWhoami(output) {
     }
     return "";
 }
+const EMAIL_RECIPIENT = /^[^\s@]+@[^\s@]+$/;
+const COGNITO_SUB = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Outpost jobs may record `owner` as the owner's Cognito user id (the box's
+ * OUTPOST_USER_ID; the reconciler matches company jobs on it). `hq dm` cannot
+ * address a Cognito id: any token that is not an email or prs_/agt_ uid is
+ * treated as a channel name and bounces with "No channel named …". Map the id
+ * to the signed-in identity's email when `hq whoami --json` reports the same
+ * subject, directly or as the human an Outpost session acts for.
+ */
+function resolveCognitoOwner(owner, deps) {
+    if (!deps.commandExists("hq"))
+        return "";
+    let parsed;
+    try {
+        const raw = deps.run("hq", ["whoami", "--json"], { cwd: deps.cwd, env: deps.env, captureStdout: true }).stdout;
+        const value = JSON.parse(raw);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return "";
+        parsed = value;
+    }
+    catch {
+        return "";
+    }
+    const target = owner.toLowerCase();
+    for (const [subKey, emailKey] of [["sub", "email"], ["delegatedSub", "delegatedEmail"]]) {
+        const sub = parsed[subKey];
+        const email = parsed[emailKey];
+        if (typeof sub === "string" && sub.toLowerCase() === target
+            && typeof email === "string" && EMAIL_RECIPIENT.test(email))
+            return email;
+    }
+    return "";
+}
 function normalizedEpoch(value) {
     if (!/^-?\d+$/.test(value))
         throw new Error(`invalid HQ_JOB_NOTIFY_NOW_EPOCH: ${value}`);
@@ -260,6 +294,17 @@ export function runJobNotify(argv, options = {}) {
         log("no owner recipient — cannot dm (logged only); never fails the job");
         deps.appendFile(deliveryLog, '{"delivered":false,"reason":"missing_owner"}\n');
     }
+    let recipient = owner;
+    const cognitoOwner = Boolean(owner) && COGNITO_SUB.test(owner);
+    if (cognitoOwner) {
+        recipient = resolveCognitoOwner(owner, deps);
+        if (recipient)
+            log(`owner ${owner} is a Cognito user id — delivering to ${recipient}`);
+        else {
+            log(`owner ${owner} is a Cognito user id that hq dm cannot address and hq whoami does not report it — set the job owner to an email or prs_ uid (logged only); never fails the job`);
+            deps.appendFile(deliveryLog, '{"delivered":false,"reason":"unresolved_owner_id"}\n');
+        }
+    }
     let previous = {};
     if (deps.exists(stateFile))
         previous = JSON.parse(deps.readFile(stateFile));
@@ -306,18 +351,22 @@ export function runJobNotify(argv, options = {}) {
         log("skip dm send — missing owner");
         deliverRc = 1;
     }
+    else if (!recipient) {
+        log("skip dm send — owner id has no dm recipient");
+        deliverRc = 1;
+    }
     else if (!dmBin) {
         log("skip dm send — hq CLI not found");
         deliverRc = 1;
     }
     else {
         const args = dmBin === "hq"
-            ? ["dm", owner, headline, "--details", details]
-            : [owner, headline, details];
+            ? ["dm", recipient, headline, "--details", details]
+            : [recipient, headline, details];
         deliverRc = deps.run(dmBin, args, { cwd: deps.cwd, env: deps.env, captureStdout: false, logPath: deliveryLog }).code;
         if (deliverRc === 0) {
             delivered = 1;
-            log(`dm delivered to ${owner} kind=${kind} job=${parsed.jobId}`);
+            log(`dm delivered to ${recipient} kind=${kind} job=${parsed.jobId}`);
         }
         else
             log(`dm delivery failed rc=${deliverRc} job=${parsed.jobId} (logged; not failing run)`);
@@ -344,6 +393,7 @@ export function runJobNotify(argv, options = {}) {
         delivered: delivered === 1,
         kind,
         owner,
+        ...(cognitoOwner ? { recipient: recipient || null } : {}),
         channel_unimplemented: channelUnimplemented === 1,
         deliver_rc: deliverRc,
     }, "compact"));

package/dist/commands/core-jobs-native.d.ts

@@ -15,6 +15,14 @@ export type ReconcileOptions = {
     fetcher?: typeof fetch;
     now?: () => Date;
 };
+/**
+ * A system unit with User=ec2-user (outpost-jobs-reconcile.service) or a cron
+ * job has no login session, so XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS are
+ * unset and `systemctl --user` fails with "Failed to connect to bus: No medium
+ * found" (feedback_6ce027d7). When the lingering user manager's runtime dir
+ * exists, point systemctl at it. Caller-provided values are kept.
+ */
+export declare function withUserBusEnvironment(env: NodeJS.ProcessEnv, uid: number | undefined, runtimeBase?: string, exists?: (file: string) => boolean): NodeJS.ProcessEnv;
 export declare function runReconcile(argv: string[], rootArg?: string, options?: ReconcileOptions): Promise<number>;
 export declare function registerCoreJobsNativeCommand(core: Command): void;
 export declare function rawArgumentsForCommand(command: Command, fallback: string[], raw?: string[]): string[];

package/dist/commands/core-jobs-native.js

@@ -379,9 +379,36 @@ Env / overrides (tests):
 
 Exit: 0 success; 1 partial failures; 2 usage/config.
 `;
-function commandResult(command, args) {
+/**
+ * A system unit with User=ec2-user (outpost-jobs-reconcile.service) or a cron
+ * job has no login session, so XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS are
+ * unset and `systemctl --user` fails with "Failed to connect to bus: No medium
+ * found" (feedback_6ce027d7). When the lingering user manager's runtime dir
+ * exists, point systemctl at it. Caller-provided values are kept.
+ */
+export function withUserBusEnvironment(env, uid, runtimeBase = "/run/user", exists = fs.existsSync) {
+    if (uid === undefined)
+        return env;
+    const next = { ...env };
+    if (!next.XDG_RUNTIME_DIR) {
+        const directory = path.posix.join(runtimeBase, String(uid));
+        if (!exists(directory))
+            return next;
+        next.XDG_RUNTIME_DIR = directory;
+    }
+    if (!next.DBUS_SESSION_BUS_ADDRESS && exists(path.posix.join(next.XDG_RUNTIME_DIR, "bus"))) {
+        next.DBUS_SESSION_BUS_ADDRESS = `unix:path=${next.XDG_RUNTIME_DIR}/bus`;
+    }
+    return next;
+}
+function schedulerCommandResult(command, args) {
+    const env = withUserBusEnvironment(process.env, typeof process.getuid === "function" ? process.getuid() : undefined, process.env.HQ_JOB_USER_RUNTIME_BASE || "/run/user");
+    return commandResult(command, args, env);
+}
+function commandResult(command, args, env = process.env) {
     const result = spawnSync(command, args, {
         encoding: "utf8",
+        env,
         stdio: ["ignore", "pipe", "pipe"],
     });
     return {
@@ -486,6 +513,11 @@ function resolveBoxOwners(options) {
                 email = shellText(record.email ?? user?.email);
                 add(email);
                 add(shellText(record.personUid ?? record.person_uid ?? record.uid));
+                // The person (or the human an Outpost session acts for) by Cognito
+                // id and email, so a job owner written either way matches the box.
+                add(shellText(record.sub));
+                add(shellText(record.delegatedEmail));
+                add(shellText(record.delegatedSub));
             }
             if (!email) {
                 const humanEmail = /.*Email:\s*(.*)/i.exec(who)?.[1]
@@ -757,7 +789,7 @@ function systemctlResult(args, dryRun, command, options) {
         return { status: 127, stdout: "", stderr: "scheduler stub was requested but no injected runner was supplied" };
     }
     try {
-        const runner = options.schedulerRunner ?? commandResult;
+        const runner = options.schedulerRunner ?? schedulerCommandResult;
         return runner(command, ["--user", ...args]);
     }
     catch (error) {

package/dist/commands/core-policy.js

@@ -4,6 +4,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { policyValidatorDiagnostic } from '../lib/policy-validator.js';
+import { evaluateTrigger } from '../utils/core-eval-trigger.js';
 import { packageRoot, resolveLiveRoot } from '../utils/hq-roots.js';
 import { describeCoreCommand } from './core-command-catalog.js';
 import { runPolicyFrontmatter as runPolicyFrontmatterImpl } from './core-policy-frontmatter.js';
@@ -165,12 +166,46 @@ function frontmatterScalar(file, key) {
             value = value.replace(/^["']|["']$/g, '');
         if (key === 'source' || key === 'created')
             value = value.replaceAll('"', '');
-        if (key === 'created')
+        if (key === 'updated')
+            value = value.replace(/^["']|["']$/g, '');
+        if (key === 'created' || key === 'updated')
             return value.slice(0, 10);
         return value;
     }
     return '';
 }
+/**
+ * The `when:` expression as inject-policy-on-trigger.sh reads it: the last
+ * `when:` line in the frontmatter, trailing ` # comment` removed, surrounding
+ * quotes stripped. Returns the expression when the canonical trigger evaluator
+ * (the one behind eval-trigger.sh) rejects it as malformed, so the policy can
+ * never match an event; undefined when it parses or there is no `when:`.
+ */
+function malformedTrigger(text) {
+    const lines = text.split('\n');
+    if (!(lines[0] ?? '').startsWith('---'))
+        return undefined;
+    let depth = 0;
+    let when;
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/\r$/, '');
+        if (/^---[ \t]*$/.test(line)) {
+            depth += 1;
+            if (depth === 2)
+                break;
+            continue;
+        }
+        if (depth !== 1 || !line.startsWith('when:'))
+            continue;
+        when = line
+            .replace(/^when:[ \t]*/, '')
+            .replace(/[ \t]+#.*$/, '')
+            .replace(/^["']|["']$/g, '');
+    }
+    if (when === undefined || when.trim() === '')
+        return undefined;
+    return evaluateTrigger(when, '') === 2 ? when : undefined;
+}
 function ruleBody(file) {
     const text = fileText(file) ?? '';
     const lines = text.split('\n');
@@ -438,8 +473,18 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
             const enforcement = frontmatterScalar(file, 'enforcement') || 'unset';
             const source = frontmatterScalar(file, 'source');
             const version = frontmatterScalar(file, 'version');
-            const createdEpoch = epochFromDate(frontmatterScalar(file, 'created')) || statMtimeSeconds(file) || 0;
+            const mtimeEpoch = statMtimeSeconds(file);
+            const createdEpoch = epochFromDate(frontmatterScalar(file, 'created')) || mtimeEpoch || 0;
             const ageDays = Math.trunc((now - createdEpoch) / 86400);
+            // Usage history counts only from the last change to the policy (and so
+            // to its trigger): `updated:` frontmatter or the file mtime, whichever is
+            // newer. A trigger that was malformed and was just repaired is not judged
+            // on the period when it could not fire. An mtime later than the report
+            // clock (pinned clock or clock skew) is not a usable change date.
+            const changedEpoch = mtimeEpoch !== undefined && mtimeEpoch <= now ? mtimeEpoch : 0;
+            const clockEpoch = Math.max(createdEpoch, epochFromDate(frontmatterScalar(file, 'updated')), changedEpoch);
+            const clockDays = Math.trunc((now - clockEpoch) / 86400);
+            const brokenTrigger = malformedTrigger(text);
             const fired = usage.counts.get(id) ?? 0;
             const lastEpoch = usage.newest.get(id);
             const lastFired = lastEpoch === undefined ? null : new Date(lastEpoch * 1000).toISOString().slice(0, 10);
@@ -448,24 +493,30 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
             const refs = refSummary(file, root);
             const singleIncident = ['user-correction', 'session-learning', 'back-pressure-failure'].includes(source) && (version || '1') === '1';
             const classes = [];
-            if (fired === 0) {
-                const comparison = bashTestGreaterOrEqual(ageDays, parsed.minAge, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 173, platform);
+            if (brokenTrigger !== undefined) {
+                // A policy whose `when:` cannot parse never had a chance to fire, so
+                // its usage history says nothing about whether the rule is needed. It
+                // is reported as broken and never offered for retirement.
+                classes.push('malformed-trigger');
+            }
+            else if (fired === 0) {
+                const comparison = bashTestGreaterOrEqual(clockDays, parsed.minAge, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 173, platform);
                 stderr += comparison.stderr;
                 if (comparison.value && usage.anyFiles)
                     classes.push('never-fired');
             }
-            if (fired > 0) {
-                const comparison = bashTestGreaterOrEqual(lastAge, parsed.dormantDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 174, platform);
+            if (brokenTrigger === undefined && fired > 0) {
+                const comparison = bashTestGreaterOrEqual(Math.min(lastAge, clockDays), parsed.dormantDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 174, platform);
                 stderr += comparison.stderr;
                 if (comparison.value)
                     classes.push('dormant');
             }
-            if (refs.stale.length > 0)
+            if (brokenTrigger === undefined && refs.stale.length > 0)
                 classes.push('stale-refs');
-            if (refs.renamed.length > 0)
+            if (brokenTrigger === undefined && refs.renamed.length > 0)
                 classes.push('renamed-refs');
-            if (singleIncident) {
-                const comparison = bashTestGreaterOrEqual(ageDays, parsed.incidentDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 178, platform);
+            if (brokenTrigger === undefined && singleIncident) {
+                const comparison = bashTestGreaterOrEqual(clockDays, parsed.incidentDays, formerScriptPath(POLICY_AGE_REPORT_SCRIPT), 178, platform);
                 stderr += comparison.stderr;
                 if (comparison.value && fired <= 1)
                     classes.push('single-incident-old');
@@ -484,6 +535,7 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
                 retrieved,
                 refs_judged: refs.judged,
                 renamed_refs: refs.renamed,
+                ...(brokenTrigger === undefined ? {} : { malformed_trigger: brokenTrigger }),
             });
         }
     }
@@ -491,10 +543,14 @@ export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Mat
         const selected = parsed.candidates ? rows.filter((row) => row.candidate_classes.length > 0) : rows;
         return policyResult(0, `${JSON.stringify(selected)}\n`, stderr);
     }
-    const never = rows.filter((row) => row.fired === 0).length;
-    const staleTotal = rows.filter((row) => row.stale_refs.length > 0).length;
-    const candidateCount = rows.filter((row) => row.candidate_classes.length > 0).length;
+    const malformed = rows.filter((row) => row.malformed_trigger !== undefined);
+    const never = rows.filter((row) => row.fired === 0 && row.malformed_trigger === undefined).length;
+    const staleTotal = rows.filter((row) => row.stale_refs.length > 0 && row.malformed_trigger === undefined).length;
+    const candidateCount = rows.filter((row) => row.candidate_classes.length > 0 && row.malformed_trigger === undefined).length;
     let stdout = `policy-age-report: ${rows.length} policies, ${never} never fired, ${staleTotal} with stale references, ${candidateCount} retirement candidates (min-age ${parsed.minAge}d, dormant ${parsed.dormantDays}d, incident ${parsed.incidentDays}d)\n`;
+    if (malformed.length > 0) {
+        stdout += `policy-age-report: ${malformed.length} with a malformed when: trigger that cannot fire (fix the trigger; not retirement candidates): ${malformed.map((row) => row.id).sort().join(', ')}\n`;
+    }
     if (!parsed.candidates)
         stdout += '  (add --candidates to list them, --json for machine-readable rows)\n';
     else {
@@ -805,6 +861,13 @@ function autoRetire(options, root, cwd, env, now) {
                 continue;
         }
         let why = '';
+        if (classes.split(',').includes('malformed-trigger')) {
+            const expression = candidate.malformed_trigger ?? '';
+            reportText += `- needs-fix (not retired) **${candidate.id}** (${candidate.path}): malformed when: trigger, so it can never fire: ${expression}\n`;
+            stderr += `policy-retire: ${candidate.id} (${candidate.path}) has a malformed when: trigger and was not retired; fix it: ${expression}\n`;
+            needfix += 1;
+            continue;
+        }
         if (classes.split(',').includes('renamed-refs')) {
             reportText += `- needs-fix (not retired) **${candidate.id}** (${candidate.path}): referenced file was renamed: ${candidate.renamed_refs.join(', ')}\n`;
             needfix += 1;

package/dist/commands/library-add.d.ts

@@ -0,0 +1,120 @@
+import { Readable } from "node:stream";
+import { type CloudAssetMediaKind } from "@indigoai-us/hq-cloud";
+import type { LibraryCaptionNote, LibraryCaptionRequest } from "./library-caption.js";
+export interface LibraryCompany {
+    uid: string;
+    slug: string;
+}
+export interface LibrarySource {
+    kind: "file" | "url";
+    /** The argument as given. */
+    input: string;
+    /** File name the placeholder is written under. */
+    name: string;
+}
+export interface OpenedSource {
+    stream: Readable;
+    contentType?: string;
+}
+export interface PutResponse {
+    status: number;
+    headers: Record<string, string | undefined>;
+}
+export interface LibraryAddDeps {
+    hqRoot: string;
+    now: () => Date;
+    /** Resolve the slug to an active company membership. */
+    resolveCompany: (slug: string) => Promise<LibraryCompany>;
+    /** POST /v1/files/presign. */
+    presign: (body: Record<string, unknown>) => Promise<Response>;
+    /** Open a fresh byte stream of a source. Called once to hash and once to upload. */
+    openSource: (source: LibrarySource) => Promise<OpenedSource>;
+    /** PUT `body` (exactly `size` bytes) to a presigned URL with `headers`. */
+    put: (url: string, headers: Record<string, string>, body: Readable, size: number) => Promise<PutResponse>;
+    writePlaceholder: (file: string, text: string) => Promise<void>;
+    /**
+     * Caption one written image or video placeholder (US-006). Must not throw:
+     * a caption failure never fails the upload. Absent = no captioning.
+     */
+    caption?: (request: LibraryCaptionRequest) => Promise<LibraryCaptionNote>;
+}
+export interface LibraryAddOptions {
+    company?: string;
+    to?: string;
+    tags: string[];
+    title?: string;
+    note?: string;
+}
+export interface LibraryAddItem {
+    source: string;
+    ok: boolean;
+    /** HQ-relative placeholder path (set when written). */
+    placeholderPath?: string;
+    originalPath?: string;
+    key?: string;
+    size?: number;
+    sha256?: string;
+    /** False when the vault already held the bytes. */
+    uploaded?: boolean;
+    error?: string;
+    /** AI caption outcome, set when captioning ran for this item. */
+    caption?: LibraryCaptionNote;
+}
+export interface LibraryAddResult {
+    company: string;
+    items: LibraryAddItem[];
+}
+export declare function contentTypeFor(name: string, served?: string): string;
+export declare function mediaKindFor(contentType: string): CloudAssetMediaKind;
+/** A file name safe to place in one directory: no separators, no control chars. */
+export declare function safeAssetName(raw: string): string;
+/** Classify an argument: an http(s) URL, otherwise a local file. */
+export declare function parseSource(input: string): LibrarySource;
+/**
+ * The library directory, HQ-relative. `--to` resolves against the HQ root and
+ * must be inside `companies/<co>/`, so `hq storage fetch` can find the
+ * company vault from the placeholder path. The default is
+ * `companies/<co>/library`.
+ */
+export declare function resolveLibraryDir(hqRoot: string, options: Pick<LibraryAddOptions, "company" | "to">): {
+    slug: string;
+    dirRel: string;
+    dirAbs: string;
+};
+export declare function offloadTimestamp(now: Date): string;
+/**
+ * Testable core. Every source is hashed first, then one presign request
+ * covers all of them (hq-pro rate-limits presign per user). A 402 for the
+ * request refuses every source and writes nothing; a per-key refusal fails
+ * only that source.
+ */
+export declare function runLibraryAdd(inputs: readonly string[], options: LibraryAddOptions, deps: LibraryAddDeps): Promise<LibraryAddResult>;
+export interface LibraryTagResult {
+    placeholderPath: string;
+    tags: string[];
+    changed: boolean;
+}
+/**
+ * Add and remove tags on a library placeholder. The placeholder is parsed and
+ * re-rendered by hq-cloud's placeholder writer, then replaced atomically
+ * (temp file + rename), so a sync watcher never reads a half-written file.
+ */
+export declare function runLibraryTag(hqRoot: string, target: string, edits: {
+    add: string[];
+    remove: string[];
+}, now?: () => Date): Promise<LibraryTagResult>;
+/** Replace a placeholder atomically (temp file + rename). */
+export declare function replacePlaceholderText(file: string, text: string): Promise<void>;
+/** Open a local file or GET a URL as a Node stream. */
+export declare function openLibrarySource(source: LibrarySource): Promise<OpenedSource>;
+/**
+ * Stream a PUT with an explicit Content-Length: S3 presigned PUTs refuse
+ * chunked transfer encoding, which fetch would use for a stream body.
+ */
+export declare function streamPut(url: string, headers: Record<string, string>, body: Readable, size: number): Promise<PutResponse>;
+export declare const defaultLibraryIo: {
+    openSource: typeof openLibrarySource;
+    put: typeof streamPut;
+    writePlaceholder: (file: string, text: string) => Promise<void>;
+};
+//# sourceMappingURL=library-add.d.ts.map