@quickchatai/quickreview 0.0.0-stage → 1.2.0

package/dist/src/commands.js

@@ -0,0 +1,1335 @@
+// The overseer's action space: command files in commands/*.json, validated
+// against a closed whitelist and executed by the daemon. There is deliberately
+// no generic escape hatch — anything not on the whitelist is rejected, logged
+// loudly, and answered with a result file the overseer can read.
+//
+// Envelope: {"command": "<name>", ...payload}. Schemas are hand-rolled and
+// STRICT — unknown fields are a rejection, not a warning.
+//
+// Two issuers, decided by directory. The same vocabulary is served
+// from the daemon-owned `commands/` (and `commands/slack/`), where every
+// writer is a pi SESSION, and from `commands/operator/`, which the operator's
+// tools (`qcr drain`, the board's `u`, the deploy tab) create and write as
+// ROOT so that the daemon's uid — the uid every session runs as — cannot write
+// into it. Nothing in a command file says who wrote it; the watcher stamps
+// the issuer from the directory and the seal, and the lever handlers
+// (`src/levers.ts`) bound a session's `drain`/`pause-pr` and never an
+// operator's. A file in the operator directory without the seal is served as
+// a session's, loudly.
+import { createHash } from "node:crypto";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, watch, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { BRANCH_MAX, BRANCH_RE, isBranchName, SLUG_RE } from "./improvements.js";
+import { validateReceipt } from "./learner/receipt.js";
+import { beltRestricts } from "./slack/origin.js";
+import { SLACK_TS_RE } from "./slack/reply.js";
+/** The session-writable command vocabulary — the one list `CommandName` is
+ * read from, so a name cannot be typed without being admitted. */
+export const COMMAND_WHITELIST = [
+    "rerun-round",
+    "restart-session",
+    "resolve-terminal-failure",
+    "pause-pr",
+    "resume-pr",
+    "flag-owner",
+    "file-improvement-pr",
+    "file-issue",
+    "slack_reply",
+    "drain",
+    "retry-thread-decision",
+    "eod-curation-receipt",
+];
+/**
+ * The operator's round controls: what the viewer's input line, `msg.ts` and
+ * the companion send to a PR's running (or idle) session. `steer` goes straight
+ * to the running session (rule 9's one exception), `follow-up` queues behind
+ * the turn, `abort-round` stops the round, and `message` is the idle PR's line
+ * (`may_post` marks one the operator allows to post). `takeover`, `release` and
+ * `debug-round` take, free and replace the PR's host. They are operator
+ * commands, so they are valid only from the root-sealed channel, and no session
+ * or Slack turn can spell them. The daemon acts on them through the optional
+ * `operatorControl` dep; a daemon without it refuses with a reason.
+ */
+export const CONTROL_COMMANDS = [
+    "steer",
+    "follow-up",
+    "abort-round",
+    "message",
+    "takeover",
+    "release",
+    "debug-round",
+];
+/** The longest `text` a steer, follow-up or message carries, in characters. */
+export const CONTROL_TEXT_MAX = 8000;
+/**
+ * The operator's commands: the lesson kill switch and the archiver's two
+ * verbs (`archive-run`, one immediate bounded archiver tick, and
+ * `archive-restore`, one PR's archive back to its live paths, both run under
+ * the archiver's strict mutex). They are not in `COMMAND_WHITELIST` — the
+ * vocabulary a session (the overseer, the EOD curator, a Slack turn) may
+ * write — and they validate only for a file the watcher found in the
+ * root-sealed `commands/operator/` directory (`operatorSealVerdict`). A
+ * session's command file cannot spell them: in the session directories, and
+ * in an UNSEALED operator directory (served as a session's), they are refused
+ * at validation, and `executeCommand` refuses
+ * them again for any issuer but the operator. `review-now` is the operator's
+ * "review this PR now": one PR queued as a human-asked round, exactly as a
+ * fresh trigger label would queue it, with no GitHub write to ask for it (the
+ * onboarding wizard's proof round sends it). The kill switch's state lives
+ * in state.db (src/lessonledger.ts), never as a memory tag anyone holding a
+ * key could write.
+ */
+export const OPERATOR_COMMANDS = [
+    "lessons-off",
+    "lessons-on",
+    "suppress-lesson",
+    "unsuppress-lesson",
+    "archive-run",
+    "archive-restore",
+    "review-now",
+    ...CONTROL_COMMANDS,
+];
+/** A lesson the operator names: the full memory URI of one entry
+ * (`viking://user/<user>/memories/<area>/<file>.md`) — `qcr lessons
+ * suppress` expands a bare `experiences/<file>.md` to it. */
+export const LESSON_URI_RE = /^viking:\/\/user\/[A-Za-z0-9_-]{1,64}\/memories\/(?:[a-z][a-z0-9_-]*\/){1,2}[A-Za-z0-9._-]{1,200}\.md$/;
+function isOperatorCommand(name) {
+    return OPERATOR_COMMANDS.includes(name);
+}
+/**
+ * Retired command spellings, folded to their current name at validate time —
+ * the codebase's ESCALATE→NEEDS_HUMAN pattern: accepted on input (sessions on
+ * older prompts may still emit them), never emitted by us — the parsed
+ * `Command`, the result file and the event ledger all carry the current name.
+ * Pinned by tests/legacy-acceptance.test.ts; an entry here is a permanent
+ * belt, not a cleanup candidate.
+ */
+const LEGACY_COMMAND_NAMES = {
+    "flag-owner-legacy": "flag-owner",
+};
+// ---- hand-rolled schema validation ----
+function fieldError(obj, allowed) {
+    const unknown = Object.keys(obj).filter((k) => k !== "command" && !allowed.includes(k));
+    return unknown.length > 0 ? `unknown field(s): ${unknown.join(", ")}` : null;
+}
+function isPrNumber(v) {
+    return typeof v === "number" && Number.isInteger(v) && v > 0;
+}
+function isGitHubId(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) && v > 0;
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.trim().length > 0;
+}
+/** The optional `for_min` of a lever command: absent, or a positive integer.
+ * The CAP is not checked here — the validator does not know the channel; the
+ * lever handler applies it with the issuer in hand. */
+function forMinField(obj) {
+    const v = obj["for_min"];
+    if (v === undefined)
+        return { ok: true, value: undefined };
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
+        return {
+            ok: false,
+            reason: "'for_min' must be a positive integer number of minutes when present",
+        };
+    }
+    return { ok: true, value: v };
+}
+/** Validate a parsed command file against the whitelist + per-command schema. */
+export function validateCommand(raw, opts = {}) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, reason: "command file must be a JSON object" };
+    }
+    const obj = raw;
+    const name = obj["command"];
+    if (typeof name !== "string")
+        return { ok: false, reason: "missing 'command' field" };
+    if (isOperatorCommand(name)) {
+        if (opts.issuer !== "operator")
+            return {
+                ok: false,
+                reason: `command '${name}' is the OPERATOR's alone: it is accepted only from the root-sealed commands/operator/ ` +
+                    "channel (`qcr lessons off|on|suppress|unsuppress`, `qcr archive run|restore`, `qcr review-now`), never from a session's command file",
+            };
+        return validateOperatorCommand(name, obj);
+    }
+    // Legacy-name fold FIRST: an aliased spelling validates against — and parses
+    // into — its current name, so downstream (tier table, dispatch, result
+    // files) never sees the retired spelling.
+    const canonical = LEGACY_COMMAND_NAMES[name] ?? name;
+    if (!COMMAND_WHITELIST.includes(canonical)) {
+        // A retired command gets its own reason: a session spawned on an older
+        // prompt can still emit it and should learn why, not just "unknown". The
+        // hint is read by a model, so it must not describe a NEEDS_HUMAN park
+        // either — no such park exists.
+        if (name === "mark-escalation-worthy") {
+            return {
+                ok: false,
+                reason: "command 'mark-escalation-worthy' was RETIRED on 2026-08-18: escalation-worthiness no longer exists, " +
+                    "and the review is never handed to a person — every round decides APPROVE or REQUEST_CHANGES on the merits. " +
+                    "Use pause-pr to hold one, or flag-owner (formerly flag-owner-legacy — the old name is still accepted) to raise it.",
+            };
+        }
+        return {
+            ok: false,
+            reason: `command '${name}' is not whitelisted (allowed: ${COMMAND_WHITELIST.join(", ")})`,
+        };
+    }
+    switch (canonical) {
+        case "rerun-round": {
+            const err = fieldError(obj, ["pr"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            return { ok: true, command: { command: "rerun-round", pr: obj["pr"] } };
+        }
+        case "restart-session": {
+            const err = fieldError(obj, ["pr"]);
+            if (err)
+                return { ok: false, reason: err };
+            const pr = obj["pr"];
+            if (!isPrNumber(pr)) {
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            }
+            return { ok: true, command: { command: "restart-session", pr: pr } };
+        }
+        case "resolve-terminal-failure": {
+            const err = fieldError(obj, ["pr", "incident_id", "command_id", "head_sha"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            for (const field of ["incident_id", "command_id"]) {
+                if (!isNonEmptyString(obj[field]))
+                    return { ok: false, reason: `'${field}' must be a non-empty string` };
+            }
+            // An authoritative GitHub 404 can legitimately correspond to a legacy
+            // synthetic debt whose stored head is the empty string. Closed PRs are
+            // still forced to a non-empty exact match by resolveTerminalFailure().
+            if (typeof obj["head_sha"] !== "string")
+                return { ok: false, reason: "'head_sha' must be a string" };
+            if (obj["incident_id"] !== `review-failure:${obj["command_id"]}`) {
+                return {
+                    ok: false,
+                    reason: "'incident_id' must exactly equal review-failure:<command_id>",
+                };
+            }
+            return {
+                ok: true,
+                command: {
+                    command: "resolve-terminal-failure",
+                    pr: obj["pr"],
+                    incident_id: obj["incident_id"],
+                    command_id: obj["command_id"],
+                    head_sha: obj["head_sha"],
+                },
+            };
+        }
+        case "pause-pr": {
+            const err = fieldError(obj, ["pr", "reason", "for_min"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            if (!isNonEmptyString(obj["reason"]))
+                return { ok: false, reason: "'reason' must be a non-empty string" };
+            const forMin = forMinField(obj);
+            if (!forMin.ok)
+                return forMin;
+            return {
+                ok: true,
+                command: {
+                    command: "pause-pr",
+                    pr: obj["pr"],
+                    reason: obj["reason"],
+                    ...(forMin.value === undefined ? {} : { for_min: forMin.value }),
+                },
+            };
+        }
+        case "resume-pr": {
+            const err = fieldError(obj, ["pr"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            return { ok: true, command: { command: "resume-pr", pr: obj["pr"] } };
+        }
+        case "flag-owner": {
+            const err = fieldError(obj, ["message"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isNonEmptyString(obj["message"]))
+                return { ok: false, reason: "'message' must be a non-empty string" };
+            return { ok: true, command: { command: "flag-owner", message: obj["message"] } };
+        }
+        case "file-improvement-pr": {
+            const err = fieldError(obj, ["branch", "title", "body", "slug"]);
+            if (err)
+                return { ok: false, reason: err };
+            for (const f of ["branch", "title", "body", "slug"]) {
+                if (!isNonEmptyString(obj[f]))
+                    return { ok: false, reason: `'${f}' must be a non-empty string` };
+            }
+            const slug = obj["slug"];
+            if (!SLUG_RE.test(slug)) {
+                return {
+                    ok: false,
+                    reason: `'slug' must match ${SLUG_RE.source} (it becomes bot/improve-<slug>)`,
+                };
+            }
+            // The session writes `branch` and the daemon hands it to git: only a
+            // plain local branch name passes — never an option (`--quiet`), a force
+            // refspec (`+wip/x`), a refspec (`a:b`) or a revision expression (`a..b`).
+            const branch = obj["branch"];
+            if (!isBranchName(branch)) {
+                return {
+                    ok: false,
+                    reason: `'branch' must be a plain local branch name matching ${BRANCH_RE.source} (at most ${BRANCH_MAX} chars)`,
+                };
+            }
+            return {
+                ok: true,
+                command: {
+                    command: "file-improvement-pr",
+                    branch,
+                    title: obj["title"],
+                    body: obj["body"],
+                    slug,
+                },
+            };
+        }
+        case "file-issue": {
+            // `pr` is optional provenance — the PR a deferral's ticket was filed
+            // from. The review session files the ticket itself, in the round that
+            // deferred; `pr` attributes the filing — and a cap refusal, which then
+            // leaves a `deferral_ticket_refused` anomaly — to that PR, so the refusal
+            // is visible where the deferral happened. It grants no rights and lifts
+            // no cap.
+            const err = fieldError(obj, ["title", "body", "pr"]);
+            if (err)
+                return { ok: false, reason: err };
+            for (const f of ["title", "body"]) {
+                if (!isNonEmptyString(obj[f]))
+                    return { ok: false, reason: `'${f}' must be a non-empty string` };
+            }
+            if (obj["pr"] !== undefined && !isPrNumber(obj["pr"])) {
+                return { ok: false, reason: "'pr' must be a positive integer when present" };
+            }
+            return {
+                ok: true,
+                command: {
+                    command: "file-issue",
+                    title: obj["title"],
+                    body: obj["body"],
+                    ...(obj["pr"] === undefined ? {} : { pr: obj["pr"] }),
+                },
+            };
+        }
+        case "drain": {
+            const err = fieldError(obj, ["on", "for_min", "hold"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (typeof obj["on"] !== "boolean") {
+                return {
+                    ok: false,
+                    reason: "'on' must be a boolean (true = engage the drain, false = lift it)",
+                };
+            }
+            const forMin = forMinField(obj);
+            if (!forMin.ok)
+                return forMin;
+            if (forMin.value !== undefined && !obj["on"])
+                return { ok: false, reason: "'for_min' only applies with on = true" };
+            const hold = obj["hold"];
+            if (hold !== undefined && typeof hold !== "boolean")
+                return { ok: false, reason: "'hold' must be a boolean" };
+            if (hold === true && !obj["on"])
+                return { ok: false, reason: "'hold' only applies with on = true (drain off lifts a hold)" };
+            if (hold === true && forMin.value !== undefined)
+                return {
+                    ok: false,
+                    reason: "'hold' has no expiry; 'for_min' and 'hold' exclude each other",
+                };
+            return {
+                ok: true,
+                command: {
+                    command: "drain",
+                    on: obj["on"],
+                    ...(forMin.value === undefined ? {} : { for_min: forMin.value }),
+                    ...(hold === true ? { hold: true } : {}),
+                },
+            };
+        }
+        case "retry-thread-decision": {
+            const err = fieldError(obj, ["comment_id"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isGitHubId(obj["comment_id"]))
+                return { ok: false, reason: "'comment_id' must be a positive safe integer" };
+            return {
+                ok: true,
+                command: { command: "retry-thread-decision", comment_id: obj["comment_id"] },
+            };
+        }
+        case "eod-curation-receipt": {
+            const res = validateReceipt(obj);
+            if (!res.ok)
+                return res;
+            return { ok: true, command: { command: "eod-curation-receipt", ...res.receipt } };
+        }
+        case "slack_reply": {
+            const err = fieldError(obj, ["thread", "text"]);
+            if (err)
+                return { ok: false, reason: err };
+            // No `channel` field, by construction: the daemon binds every reply to
+            // cfg.slack.channel, so posting in the wrong place is unrepresentable.
+            if (!isNonEmptyString(obj["thread"]) || !SLACK_TS_RE.test(obj["thread"])) {
+                return {
+                    ok: false,
+                    reason: "'thread' must be a Slack message ts like \"1712345678.123456\"",
+                };
+            }
+            if (!isNonEmptyString(obj["text"]))
+                return { ok: false, reason: "'text' must be a non-empty string" };
+            return {
+                ok: true,
+                command: { command: "slack_reply", thread: obj["thread"], text: obj["text"] },
+            };
+        }
+    }
+}
+/** The operator commands' strict schemas (the issuer was checked first). */
+function validateOperatorCommand(name, obj) {
+    switch (name) {
+        case "lessons-off":
+        case "lessons-on": {
+            const err = fieldError(obj, []);
+            if (err)
+                return { ok: false, reason: err };
+            return { ok: true, command: { command: name } };
+        }
+        case "suppress-lesson":
+        case "unsuppress-lesson": {
+            const err = fieldError(obj, ["uri"]);
+            if (err)
+                return { ok: false, reason: err };
+            const uri = obj["uri"];
+            if (typeof uri !== "string" || !LESSON_URI_RE.test(uri) || uri.includes(".."))
+                return {
+                    ok: false,
+                    reason: "'uri' must be one memory entry's full URI (viking://user/<user>/memories/<area>/<file>.md)",
+                };
+            return { ok: true, command: { command: name, uri } };
+        }
+        case "archive-run": {
+            const err = fieldError(obj, []);
+            if (err)
+                return { ok: false, reason: err };
+            return { ok: true, command: { command: "archive-run" } };
+        }
+        case "archive-restore": {
+            const err = fieldError(obj, ["pr"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            return { ok: true, command: { command: "archive-restore", pr: obj["pr"] } };
+        }
+        case "review-now": {
+            const err = fieldError(obj, ["pr"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            return { ok: true, command: { command: "review-now", pr: obj["pr"] } };
+        }
+        case "steer":
+        case "follow-up":
+        case "message": {
+            const err = fieldError(obj, name === "message" ? ["pr", "text", "may_post"] : ["pr", "text"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            const text = obj["text"];
+            if (!isNonEmptyString(text) || text.length > CONTROL_TEXT_MAX)
+                return {
+                    ok: false,
+                    reason: `'text' must be a non-empty string of at most ${CONTROL_TEXT_MAX} characters`,
+                };
+            if (name !== "message")
+                return { ok: true, command: { command: name, pr: obj["pr"], text } };
+            const mayPost = obj["may_post"];
+            if (mayPost !== undefined && typeof mayPost !== "boolean")
+                return { ok: false, reason: "'may_post' must be a boolean when present" };
+            return {
+                ok: true,
+                command: {
+                    command: "message",
+                    pr: obj["pr"],
+                    text,
+                    ...(mayPost === undefined ? {} : { may_post: mayPost }),
+                },
+            };
+        }
+        case "abort-round":
+        case "takeover":
+        case "release":
+        case "debug-round": {
+            const err = fieldError(obj, ["pr"]);
+            if (err)
+                return { ok: false, reason: err };
+            if (!isPrNumber(obj["pr"]))
+                return { ok: false, reason: "'pr' must be a positive integer" };
+            return { ok: true, command: { command: name, pr: obj["pr"] } };
+        }
+    }
+}
+// ---- tier enforcement ----
+/**
+ * Commands a Slack turn may run, by tier. The table is data on purpose: adding
+ * a command without deciding its tier is then impossible to do by accident.
+ *
+ * `own` = allowed for tier `author` only when the target PR is in the origin's
+ * `authorized_prs` (recomputed by the router from `pr_state.author`, NEVER read
+ * out of the inject body).
+ *
+ * `owner` is the owner's tier (legacy persisted records with the retired tier
+ * spelling fold to it on read). The `companion` tier is not a column: it is the
+ * owner's column read again (`tierAllows`), so the two are one shared set and a
+ * verb added for the owner is the companion's in the same edit (by ruling:
+ * the companion can do everything the owner can). `system` is the
+ * daemon's own unattended turns (`OriginStore.writeLocal`): it is `true` on
+ * every row but the operator's round controls (`CONTROL_COMMANDS`, which a
+ * daemon turn has no standing to send) because a
+ * daemon turn with NO origin record already runs unrestricted —
+ * `authorizeCommand(_, null)` ⇒ ok, and that null-origin rule is unchanged.
+ * The column is the stamped, auditable form of that same
+ * standing authority; it never widens anything, and a Slack turn can never
+ * reach it (`computeTier` never returns `system`).
+ *
+ * Nothing here can reach the dry_run flag, a deploy, an approval or anything
+ * review-dismissing: those are not commands at all, and this feature adds no
+ * GitHub mutation — every write still goes through the MutationGate.
+ */
+const TIER_TABLE = {
+    "rerun-round": { anyone: false, author: "own", owner: true, system: true },
+    "pause-pr": { anyone: false, author: "own", owner: true, system: true },
+    "resume-pr": { anyone: false, author: "own", owner: true, system: true },
+    // The safety valve: anyone may always reach a human.
+    "flag-owner": { anyone: true, author: true, owner: true, system: true },
+    "restart-session": { anyone: false, author: false, owner: true, system: true },
+    // Terminal debt cleanup is destructive and never author-reachable. Its
+    // handler additionally requires exact identity + authoritative terminality.
+    "resolve-terminal-failure": { anyone: false, author: false, owner: true, system: true },
+    // improvements.ts caps still apply ON TOP — a tier never lifts a cap.
+    "file-improvement-pr": { anyone: false, author: false, owner: true, system: true },
+    // The review session files a deferral's ticket itself, in the round that
+    // deferred — there is no author confirmation step. Its command files land
+    // in the `commands/` dir with no Slack origin, which already runs at full
+    // (system-column) autonomy, so the deferral path needs no widening here. On
+    // Slack, `file-issue` is the owner's alone. The day cap, the dedup and the
+    // gate all still apply downstream — a tier never lifts a cap.
+    "file-issue": { anyone: false, author: false, owner: true, system: true },
+    // Not user-tiered: gated by channel binding, thread, caps, cooldown, length.
+    slack_reply: { anyone: true, author: true, owner: true, system: true },
+    // Deploy-window drain: an operator lever (same standing as restart-session)
+    // — it stops the whole board, so it is never author-reachable.
+    drain: { anyone: false, author: false, owner: true, system: true },
+    "retry-thread-decision": { anyone: false, author: false, owner: true, system: true },
+    // The EOD curator's receipt — a daemon (system) turn's, or the
+    // owner's; never a Slack author's or anyone's.
+    "eod-curation-receipt": { anyone: false, author: false, owner: true, system: true },
+    // The operator's round controls reach the daemon only from the sealed
+    // operator channel (`validateCommand`), so this row never admits a Slack
+    // turn; it is the verb set the owner and the companion share. A daemon turn
+    // (`system`) never steers, takes over or releases a PR.
+    steer: { anyone: false, author: false, owner: true, system: false },
+    "follow-up": { anyone: false, author: false, owner: true, system: false },
+    "abort-round": { anyone: false, author: false, owner: true, system: false },
+    message: { anyone: false, author: false, owner: true, system: false },
+    takeover: { anyone: false, author: false, owner: true, system: false },
+    release: { anyone: false, author: false, owner: true, system: false },
+    "debug-round": { anyone: false, author: false, owner: true, system: false },
+};
+/** May `tier` send `name`? `companion` reads the owner's column: one set. */
+export function tierAllows(tier, name) {
+    const row = TIER_TABLE[name];
+    if (!row)
+        return false;
+    return tier === "system" ? row.system : row.owner;
+}
+/** Every verb `tier` may send, in table order. */
+export function tierVerbs(tier) {
+    return Object.keys(TIER_TABLE).filter((name) => tierAllows(tier, name));
+}
+/** Target PR of a command, when it has one. */
+function targetPr(command) {
+    if (command.command === "restart-session")
+        return typeof command.pr === "number" ? command.pr : null;
+    return "pr" in command && typeof command.pr === "number" ? command.pr : null;
+}
+/**
+ * May this command run on behalf of `origin`?
+ *
+ * `origin === null` means "no Slack turn is live" — the command came from the
+ * daemon itself (EOD sweep, anomaly wake) or from the owner at the tmux pane,
+ * and keeps full autonomy (the same rights the `system` tier stamps
+ * explicitly). A caller that must fail closed (the Slack command directory)
+ * checks for a missing origin BEFORE calling this.
+ *
+ * Every rejection reason starts with `tier: ` so the overseer — and the
+ * `command_rejected` event stream — can tell a rights refusal from a cap.
+ */
+export function authorizeCommand(command, origin) {
+    if (isOperatorCommand(command.command))
+        return {
+            ok: false,
+            reason: `tier: '${command.command}' is the operator's alone (commands/operator/), never a Slack turn's`,
+        };
+    if (origin === null)
+        return { ok: true };
+    const row = TIER_TABLE[command.command];
+    const pr = targetPr(command);
+    switch (origin.tier) {
+        case "owner":
+            return row.owner
+                ? { ok: true }
+                : { ok: false, reason: `tier: '${command.command}' is not available` };
+        case "system":
+            return row.system
+                ? { ok: true }
+                : { ok: false, reason: `tier: '${command.command}' is not available` };
+        case "author": {
+            if (row.author === true)
+                return { ok: true };
+            if (row.author === false) {
+                return {
+                    ok: false,
+                    reason: `tier: '${command.command}' requires tier owner (this turn is tier author)`,
+                };
+            }
+            if (pr === null)
+                return {
+                    ok: false,
+                    reason: `tier: '${command.command}' needs a PR number to check ownership`,
+                };
+            if (origin.authorized_prs.includes(pr))
+                return { ok: true };
+            return {
+                ok: false,
+                reason: `tier: PR #${pr} is not authored by this Slack user (authorized: ${origin.authorized_prs.length ? origin.authorized_prs.join(", ") : "none"})`,
+            };
+        }
+        default:
+            // `anyone` and `ignored` alike: read-only plus the two ungated commands.
+            return row.anyone
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: `tier: '${command.command}' is not available at tier ${origin.tier}`,
+                };
+    }
+}
+/**
+ * May the companion send this command? Not a Slack origin: the TUI forwards a
+ * companion's action as an operator command, and checks it here first.
+ * The verbs are the owner's, no more and no fewer (`tierAllows`).
+ */
+export function authorizeCompanionCommand(command) {
+    return tierAllows("companion", command.command)
+        ? { ok: true }
+        : { ok: false, reason: `tier: '${command.command}' is not available to the companion` };
+}
+function normalize(outcome) {
+    return outcome === undefined || outcome === null ? { ok: true } : outcome;
+}
+/** Dispatch a validated command to the injected handlers. */
+export async function executeCommand(command, deps, 
+// A direct call with no context is a SESSION's: the bounded side is the
+// default, and only the operator watcher ever stamps the other one.
+ctx = { file: "", issuer: "session" }) {
+    switch (command.command) {
+        case "rerun-round":
+            return normalize(await deps.rerunRound(command.pr));
+        case "restart-session":
+            return normalize(await deps.restartSession(command.pr, ...(ctx.delivery_key ? [ctx.delivery_key] : [])));
+        case "resolve-terminal-failure":
+            return normalize(await deps.resolveTerminalFailure({
+                pr: command.pr,
+                incident_id: command.incident_id,
+                command_id: command.command_id,
+                head_sha: command.head_sha,
+            }));
+        case "pause-pr":
+            return normalize(await deps.pausePr(command.pr, command.reason, ctx.issuer, command.for_min, ...(ctx.delivery_key ? [ctx.delivery_key] : [])));
+        case "resume-pr":
+            return normalize(await deps.resumePr(command.pr, ctx.issuer));
+        case "flag-owner":
+            return normalize(await deps.flagOwner(command.message));
+        case "file-improvement-pr":
+            return normalize(await deps.fileImprovementPr({
+                branch: command.branch,
+                title: command.title,
+                body: command.body,
+                slug: command.slug,
+            }, ...(ctx.delivery_key ? [ctx.delivery_key] : [])));
+        case "file-issue":
+            return normalize(await deps.fileIssue({
+                title: command.title,
+                body: command.body,
+                ...(command.pr === undefined ? {} : { pr: command.pr }),
+            }, ...(ctx.delivery_key ? [ctx.delivery_key] : [])));
+        case "slack_reply": {
+            if (!deps.slackReply)
+                return { ok: false, reason: "slack_reply is not wired (Slack is disabled)" };
+            return normalize(await deps.slackReply({
+                thread: command.thread,
+                text: command.text,
+                // Session filenames are stable replay keys, even after archival.
+                // Sealed operator rewrites are separate, versioned deliveries.
+                file: ctx.issuer === "operator" ? (ctx.delivery_key ?? ctx.file) : ctx.file,
+            }));
+        }
+        case "drain": {
+            if (!deps.drain)
+                return { ok: false, reason: "drain is not wired on this daemon" };
+            if (command.hold === true)
+                return normalize(await deps.drain(command.on, ctx.issuer, command.for_min, ctx.delivery_key, true));
+            return normalize(await deps.drain(command.on, ctx.issuer, command.for_min, ...(ctx.delivery_key ? [ctx.delivery_key] : [])));
+        }
+        case "retry-thread-decision": {
+            if (!deps.retryThreadDecision)
+                return { ok: false, reason: "retry-thread-decision is not wired on this daemon" };
+            return normalize(await deps.retryThreadDecision(command.comment_id));
+        }
+        case "eod-curation-receipt": {
+            if (!deps.curationReceipt)
+                return {
+                    ok: false,
+                    reason: "eod-curation-receipt is not wired on this daemon (no learner)",
+                };
+            return normalize(await deps.curationReceipt({ day: command.day, decisions: command.decisions }));
+        }
+        case "lessons-off":
+        case "lessons-on":
+        case "suppress-lesson":
+        case "unsuppress-lesson": {
+            // The belt behind validation's brace: whoever reached this function,
+            // only an operator-stamped context may flip the kill switch.
+            if (ctx.issuer !== "operator")
+                return {
+                    ok: false,
+                    reason: `'${command.command}' is the operator's alone — refused for issuer '${ctx.issuer}'`,
+                };
+            if (!deps.lessonSwitch)
+                return { ok: false, reason: `${command.command} is not wired on this daemon` };
+            const change = command.command === "lessons-off"
+                ? { action: "off" }
+                : command.command === "lessons-on"
+                    ? { action: "on" }
+                    : command.command === "suppress-lesson"
+                        ? { action: "suppress", uri: command.uri }
+                        : { action: "unsuppress", uri: command.uri };
+            return normalize(await deps.lessonSwitch(change, ctx.delivery_key ?? ctx.file));
+        }
+        case "archive-run":
+        case "archive-restore": {
+            // The belt behind validation's brace, as for the kill switch.
+            if (ctx.issuer !== "operator")
+                return {
+                    ok: false,
+                    reason: `'${command.command}' is the operator's alone — refused for issuer '${ctx.issuer}'`,
+                };
+            if (command.command === "archive-run") {
+                if (!deps.archiveRun)
+                    return { ok: false, reason: "archive-run is not wired on this daemon" };
+                return normalize(await deps.archiveRun(ctx.delivery_key ?? ctx.file));
+            }
+            if (!deps.archiveRestore)
+                return { ok: false, reason: "archive-restore is not wired on this daemon" };
+            return normalize(await deps.archiveRestore(command.pr, ctx.delivery_key ?? ctx.file));
+        }
+        case "review-now": {
+            // The belt behind validation's brace, as for the kill switch.
+            if (ctx.issuer !== "operator")
+                return {
+                    ok: false,
+                    reason: `'${command.command}' is the operator's alone — refused for issuer '${ctx.issuer}'`,
+                };
+            if (!deps.reviewNow)
+                return { ok: false, reason: "review-now is not wired on this daemon" };
+            return normalize(await deps.reviewNow(command.pr, ctx.delivery_key ?? ctx.file));
+        }
+        case "steer":
+        case "follow-up":
+        case "abort-round":
+        case "message":
+        case "takeover":
+        case "release":
+        case "debug-round": {
+            // The belt behind validation's brace, as for the kill switch.
+            if (ctx.issuer !== "operator")
+                return {
+                    ok: false,
+                    reason: `'${command.command}' is the operator's alone — refused for issuer '${ctx.issuer}'`,
+                };
+            if (!deps.operatorControl)
+                return { ok: false, reason: `${command.command} is not wired on this daemon` };
+            return normalize(await deps.operatorControl(command, ctx.delivery_key ?? ctx.file));
+        }
+    }
+}
+export function processOperatorSeal() {
+    return {
+        euid: process.geteuid?.() ?? -1,
+        gids: process.getgroups?.() ?? [],
+        stat(path) {
+            try {
+                // lstat, not stat: the seal is a claim about the path the operator's
+                // tools wrote, and a symlink planted at that path must show as one.
+                const s = lstatSync(path);
+                const kind = s.isSymbolicLink()
+                    ? "symlink"
+                    : s.isDirectory()
+                        ? "dir"
+                        : s.isFile()
+                            ? "file"
+                            : "other";
+                return { uid: s.uid, gid: s.gid, mode: s.mode & 0o7777, kind };
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+/** Could a process with `seal`'s identity write this path? */
+function writableBy(seal, s) {
+    if (s.uid === seal.euid)
+        return true;
+    if ((s.mode & 0o002) !== 0)
+        return true;
+    return seal.gids.includes(s.gid) && (s.mode & 0o020) !== 0;
+}
+/**
+ * Is `file` in `dir` the OPERATOR's? It is exactly when the directory is a
+ * real directory and the file a real file, and neither could have been
+ * written by the daemon's own identity — the identity every session shares.
+ * Anything else (a symlink standing in for the directory — the parent
+ * `commands/` is the daemon's, so a session can plant one — the directory
+ * made by the daemon's uid, a group- or world-writable mode, a file the
+ * daemon could edit) is not a seal, and the verdict says which.
+ */
+export function operatorSealVerdict(seal, dir, file) {
+    const d = seal.stat(dir);
+    if (!d)
+        return { sealed: false, reason: "operator directory missing" };
+    if (d.kind !== "dir")
+        return { sealed: false, reason: `operator directory is a ${d.kind}, not a directory` };
+    if (writableBy(seal, d))
+        return {
+            sealed: false,
+            reason: `operator directory is writable by uid ${seal.euid} (owner ${d.uid}, mode ${d.mode.toString(8)})`,
+        };
+    const f = seal.stat(file);
+    if (!f)
+        return { sealed: false, reason: "command file vanished" };
+    if (f.kind !== "file")
+        return { sealed: false, reason: `command file is a ${f.kind}, not a regular file` };
+    if (writableBy(seal, f))
+        return {
+            sealed: false,
+            reason: `command file is writable by uid ${seal.euid} (owner ${f.uid}, mode ${f.mode.toString(8)})`,
+        };
+    return { sealed: true };
+}
+/**
+ * The identity of one version of an operator command file — the key the
+ * handled-ledger is written under. The operator's directory is not the
+ * daemon's to archive from, so "handled" has to be remembered; remembering the
+ * name alone would make every re-used name a one-shot, silently ignoring a
+ * second write under the same name. Inode + mtime + size change on every
+ * rewrite that matters — the operator's tools land files by tmp+mv, a new
+ * inode each time — and stay put across the sweeps that re-see an unchanged
+ * file. `null` when the file is gone.
+ */
+export function operatorCommandVersion(path) {
+    try {
+        return commandVersionOf(path, statSync(path, { bigint: true }));
+    }
+    catch {
+        return null;
+    }
+}
+function commandVersionOf(path, s) {
+    return `${basename(path)}:${s.ino}:${s.mtimeNs}:${s.size}`;
+}
+/** `dev:ino` of the object AT `path` (a symlink as itself), `null` when absent. */
+function fileIdentityAt(path) {
+    try {
+        const s = lstatSync(path, { bigint: true });
+        return `${s.dev}:${s.ino}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** The inode at `path` — what `fs.watch` binds to — or `null` when nothing is there. */
+function inodeAt(path) {
+    try {
+        return statSync(path, { bigint: true }).ino;
+    }
+    catch {
+        return null;
+    }
+}
+// These handlers own richer durable recovery (filing reconciles exact GitHub
+// markers; lever/process handlers journal their effects; the remaining handlers
+// use their own delivery key). Pending recovery must reach those handlers.
+const HANDLER_RECOVERY_COMMANDS = new Set([
+    "file-improvement-pr",
+    "file-issue",
+    "pause-pr",
+    "drain",
+    "restart-session",
+    "slack_reply",
+    "lessons-off",
+    "lessons-on",
+    "suppress-lesson",
+    "unsuppress-lesson",
+]);
+export class CommandWatcher {
+    opts;
+    dir;
+    resultsDir;
+    processedDir;
+    now;
+    log;
+    watcher = null;
+    /** The inode `watcher` is bound to — `fs.watch` follows the inode, not the path. */
+    watchedIno = null;
+    parentWatcher = null;
+    sweepTimer = null;
+    inFlight = new Set();
+    /** Diagnostics only: every sweep still reads/parses the source anew. */
+    parseFailures = new Map();
+    /** Serialises handling so two file events can't race the same caps. */
+    queue = Promise.resolve();
+    constructor(opts) {
+        this.opts = opts;
+        this.dir = opts.dir;
+        const resultsRoot = opts.operator ? dirname(opts.dir) : opts.dir;
+        this.resultsDir = join(resultsRoot, "results");
+        this.processedDir = join(opts.dir, "processed");
+        this.now = opts.now ?? (() => new Date());
+        this.log = opts.log ?? ((line) => console.error(line));
+    }
+    ensureDirs() {
+        mkdirSync(this.resultsDir, { recursive: true });
+        if (this.opts.operator)
+            return; // never ours to create — see `operator`
+        mkdirSync(this.dir, { recursive: true });
+        mkdirSync(this.processedDir, { recursive: true });
+    }
+    /** Startup sweep + fs.watch. Returns once the initial sweep has completed.
+     * The operator directory may not exist yet (the operator's first write
+     * creates it): then the parent is watched for it to appear, and the sweep
+     * timer re-tries the attach as a belt. */
+    async start() {
+        this.ensureDirs();
+        // Watch FIRST, then sweep on the same queue the watch feeds: the sweep
+        // snapshots the directory and then awaits each handler, so a file a live
+        // session writes after the snapshot must already have a watcher to see
+        // it — a session dir has no periodic sweep, so a file missed here would
+        // wait for a restart. A file seen by both is handled once: the second
+        // visit finds it archived.
+        if (!this.opts.operator)
+            this.attachDirWatch();
+        const initial = this.queue.then(() => this.sweep());
+        this.queue = initial.catch((err) => this.log(`[commands] sweep failed: ${String(err)}`));
+        await initial;
+        const interval = this.opts.sweepIntervalMs ?? 15_000;
+        if (this.opts.operator && interval > 0) {
+            this.sweepTimer = setInterval(() => void this.enqueueSweep(), interval);
+            this.sweepTimer.unref?.();
+        }
+    }
+    /** Watch the served directory when it exists. True once watching. */
+    attachDirWatch() {
+        if (this.watcher)
+            return true;
+        const ino = inodeAt(this.dir);
+        if (ino === null)
+            return false;
+        this.watcher = watch(this.dir, (_event, filename) => {
+            if (!filename) {
+                void this.enqueueSweep();
+                return;
+            }
+            const name = filename.toString();
+            if (!name.endsWith(".json"))
+                return;
+            void this.enqueue(join(this.dir, name));
+        });
+        this.watchedIno = ino;
+        this.parentWatcher?.close();
+        this.parentWatcher = null;
+        return true;
+    }
+    detachDirWatch() {
+        this.watcher?.close();
+        this.watcher = null;
+        this.watchedIno = null;
+    }
+    /**
+     * Operator dir only: keep the watch on whatever directory is AT the path
+     * now. `fs.watch` binds to an inode, and the parent `commands/` is the
+     * daemon's — so a session can rename the sealed directory away and put
+     * another in its place, and a watcher left on the old inode would see none
+     * of the new one's files. Every sweep re-checks; a directory that is gone
+     * or replaced drops the old watch, a present one is attached, and an absent
+     * one leaves the parent watched for it to appear.
+     */
+    syncDirWatch() {
+        if (this.watcher && inodeAt(this.dir) !== this.watchedIno)
+            this.detachDirWatch();
+        if (!this.attachDirWatch() && !this.parentWatcher) {
+            this.parentWatcher = watch(dirname(this.dir), (_event, filename) => {
+                if (filename?.toString() === basename(this.dir))
+                    void this.enqueueSweep();
+            });
+        }
+    }
+    stop() {
+        this.detachDirWatch();
+        this.parentWatcher?.close();
+        this.parentWatcher = null;
+        if (this.sweepTimer)
+            clearInterval(this.sweepTimer);
+        this.sweepTimer = null;
+    }
+    /** Handle every pending <dir>/*.json once. */
+    async sweep() {
+        this.ensureDirs();
+        if (this.opts.operator)
+            this.syncDirWatch();
+        if (!existsSync(this.dir))
+            return;
+        const names = readdirSync(this.dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(".json"))
+            .map((e) => e.name)
+            .sort();
+        for (const name of names)
+            await this.handleFile(join(this.dir, name));
+    }
+    enqueueSweep() {
+        this.queue = this.queue
+            .then(() => this.sweep())
+            .catch((err) => this.log(`[commands] sweep failed: ${String(err)}`));
+        return this.queue;
+    }
+    enqueue(path) {
+        this.queue = this.queue
+            .then(async () => {
+            await this.handleFile(path);
+        })
+            .catch((err) => this.log(`[commands] ${path}: ${String(err)}`));
+        return this.queue;
+    }
+    /**
+     * Read and parse one command file. `identity` names the file object the
+     * parsed bytes came from (`dev:ino` of the open descriptor) so the operator
+     * seal can be checked against THOSE bytes rather than against whatever
+     * stands at the path a moment earlier or later (the parent `commands/` is
+     * the daemon's, so a session can swap the directory between two syscalls).
+     * `version` is the handled-ledger key of those same bytes
+     * (`operatorCommandVersion`'s), so a file replaced during a parse retry is
+     * recorded as the version that ran, not the one first seen. The descriptor
+     * is stat'ed before AND after the read, and a read the two disagree on (a
+     * writer's write landed in between) is retried like a partial one — so the
+     * version always names the bytes parsed. `text` is those bytes; a failed
+     * read still returns the last text it read, when it read one. The
+     * operator directory is opened without following a symlink.
+     */
+    async readCommandFile(path) {
+        const attempts = this.opts.parseAttempts ?? 3;
+        const delay = this.opts.parseRetryMs ?? 40;
+        const flags = this.opts.operator
+            ? fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW
+            : fsConstants.O_RDONLY;
+        let lastError = "unreadable";
+        let lastVersion = null;
+        let lastText = null;
+        for (let i = 0; i < attempts; i++) {
+            if (!existsSync(path))
+                return { ok: false, reason: "file disappeared", version: null, text: null };
+            try {
+                const fd = openSync(path, flags);
+                let text;
+                let identity;
+                let version;
+                let stable;
+                try {
+                    const st = fstatSync(fd, { bigint: true });
+                    identity = `${st.dev}:${st.ino}`;
+                    text = readFileSync(fd, "utf8");
+                    version = commandVersionOf(path, fstatSync(fd, { bigint: true }));
+                    stable = version === commandVersionOf(path, st);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                lastVersion = version;
+                lastText = text;
+                if (!stable) {
+                    lastError = "changed while it was read";
+                }
+                else if (text.trim().length === 0) {
+                    lastError = "empty file";
+                }
+                else {
+                    return { ok: true, value: JSON.parse(text), identity, version, text };
+                }
+            }
+            catch (err) {
+                // A partially-written file is expected transiently — retry before rejecting.
+                lastError = err.message;
+            }
+            if (i < attempts - 1)
+                await new Promise((r) => setTimeout(r, delay));
+        }
+        return {
+            ok: false,
+            reason: `malformed JSON: ${lastError}`,
+            version: lastVersion,
+            text: lastText,
+        };
+    }
+    /**
+     * Who wrote this file, as far as the daemon can PROVE it. A session
+     * directory's writer is a session. The operator directory's writer is the
+     * operator only when the seal holds; a file there without it is served as a
+     * session's — loudly, with the reason in the ledger — so an unsealed channel
+     * degrades to the bounded side and never to the unbounded one.
+     */
+    issuerFor(path, readIdentity) {
+        const seal = this.opts.operator;
+        if (!seal)
+            return "session";
+        // Checked AFTER the read, and then bound to it: the file at the path must
+        // still be the very object whose bytes were parsed. Otherwise a directory
+        // swapped in for the read and swapped back for the seal check would lend
+        // its bytes the operator's authority.
+        let verdict = operatorSealVerdict(seal, this.dir, path);
+        if (verdict.sealed && readIdentity !== null && fileIdentityAt(path) !== readIdentity)
+            verdict = { sealed: false, reason: "command file replaced while it was read" };
+        if (verdict.sealed)
+            return "operator";
+        this.opts.store.logEvent("operator_channel_unsealed", null, {
+            file: basename(path),
+            reason: verdict.reason,
+        });
+        this.log(`[commands] ${basename(path)}: operator channel NOT sealed (${verdict.reason}) — served as a session's command`);
+        return "session";
+    }
+    /** Validate + execute one command file, writing its result file. */
+    async handleFile(path) {
+        const name = basename(path, ".json");
+        if (this.inFlight.has(path))
+            return null;
+        if (!existsSync(path))
+            return null;
+        // An operator file cannot be archived away (the directory is not ours to
+        // write), so the store remembers what was handled across restarts — by
+        // file VERSION, so a name written again with new content is a new command
+        // and an unchanged file re-seen by the sweep is not.
+        const seen = this.opts.operator ? operatorCommandVersion(path) : null;
+        if (this.opts.operator) {
+            if (seen === null)
+                return null;
+            if (this.opts.store.operatorCommandHandled(seen))
+                return null;
+        }
+        this.inFlight.add(path);
+        try {
+            this.ensureDirs();
+            const read = await this.readCommandFile(path);
+            if (!read.ok && read.reason === "file disappeared")
+                return null;
+            // The ledger records the version whose bytes were parsed — a file
+            // replaced during a parse retry is that new version.
+            const version = this.opts.operator ? (read.version ?? seen) : null;
+            if (version !== null && version !== seen && this.opts.store.operatorCommandHandled(version))
+                return null;
+            if (!read.ok) {
+                const fingerprint = createHash("sha256")
+                    .update(JSON.stringify([read.version, read.text, read.reason]))
+                    .digest("hex");
+                if (this.parseFailures.get(path) === fingerprint)
+                    return null;
+                const result = this.finish(path, name, version, read.text, null, this.issuerFor(path, null), { ok: false, reason: `${read.reason}; file retained for a later completed write` }, true, true);
+                this.parseFailures.set(path, fingerprint);
+                if (this.parseFailures.size > 256) {
+                    const oldest = this.parseFailures.keys().next().value;
+                    if (oldest !== undefined)
+                        this.parseFailures.delete(oldest);
+                }
+                return result;
+            }
+            this.parseFailures.delete(path);
+            const issuer = this.issuerFor(path, read.identity);
+            const validation = validateCommand(read.value, { issuer });
+            if (!validation.ok) {
+                const attempted = read.value?.command;
+                return this.finish(path, name, version, read.text, typeof attempted === "string" ? attempted : null, issuer, { ok: false, reason: validation.reason }, true);
+            }
+            // The Slack belt stops a SESSION mis-filing; a sealed operator file is
+            // the human at the terminal and never rides a Slack turn. An UNSEALED
+            // operator file is a session's and gets the belt like any other.
+            const denial = issuer === "operator" ? null : this.tierCheck(validation.command);
+            if (denial)
+                return this.finish(path, name, version, read.text, validation.command.command, issuer, { ok: false, reason: denial }, true);
+            const deliveryKey = `${this.opts.scope ?? "local"}/${read.identity}/${read.version}`;
+            const receiptKey = createHash("sha256")
+                .update(JSON.stringify([deliveryKey, validation.command]))
+                .digest("hex");
+            const journal = !HANDLER_RECOVERY_COMMANDS.has(validation.command.command);
+            const reserved = !journal || this.opts.store.reserveCommandDelivery(receiptKey);
+            let outcome;
+            if (!reserved) {
+                const receipt = this.opts.store.commandDeliveryReceipt(receiptKey);
+                outcome =
+                    receipt.result === null
+                        ? {
+                            ok: false,
+                            reason: "command outcome unknown after interrupted delivery; submit a fresh command to retry",
+                        }
+                        : JSON.parse(receipt.result);
+            }
+            else {
+                try {
+                    outcome = await executeCommand(validation.command, this.opts.deps, {
+                        file: this.opts.scope ? `${this.opts.scope}/${name}` : name,
+                        delivery_key: deliveryKey,
+                        issuer,
+                    });
+                    if (journal)
+                        this.opts.store.settleCommandDelivery(receiptKey, JSON.stringify(outcome));
+                }
+                catch (err) {
+                    // The effect may already have happened. Leave its pending receipt
+                    // unknown rather than allowing a restart to repeat it.
+                    outcome = { ok: false, reason: `handler threw: ${err.message}` };
+                }
+            }
+            return this.finish(path, name, version, read.text, validation.command.command, issuer, outcome, !outcome.ok);
+        }
+        finally {
+            this.inFlight.delete(path);
+        }
+    }
+    /** Rights check between validation and execution. Returns a reason to deny. */
+    tierCheck(command) {
+        const gate = this.opts.tier;
+        if (!gate)
+            return null;
+        let origin = null;
+        try {
+            origin = gate.currentOrigin();
+        }
+        catch (err) {
+            // A gate that cannot answer denies — never fails open.
+            return `tier: origin lookup failed (${err.message})`;
+        }
+        if (gate.dir === "slack") {
+            if (!origin) {
+                return "tier: no live Slack origin for this turn — a tier-checked command needs one (fail closed)";
+            }
+            const auth = authorizeCommand(command, origin);
+            return auth.ok ? null : auth.reason;
+        }
+        // Local dir: only the belt applies. It fires on CAUSE, not on recency —
+        // a daemon-caused turn (`source: "local"`) always passes, and a Slack-caused
+        // one from a non-owner user always refuses, however old the record is.
+        // (`parseOriginRecord` folds the retired tier spelling to "owner", so this
+        // comparison only ever sees the current vocabulary; a Slack origin can
+        // never be "system" — only `writeLocal` stamps that, with source "local".)
+        if (origin && beltRestricts(origin)) {
+            return (`tier: this turn was caused by a Slack message from ${origin.slack_user} (tier ${origin.tier}) — ` +
+                `write '${command.command}' to commands/slack/ so it can be tier-checked`);
+        }
+        return null;
+    }
+    finish(path, name, 
+    /** The operator file's version key (`operatorCommandVersion`); null for a session dir. */
+    version, 
+    /** The bytes that were read; null when no file was read. */
+    readText, command, issuer, outcome, loud, unsettled = false) {
+        const result = {
+            ...outcome,
+            command,
+            file: basename(path),
+            handled_at: this.now().toISOString(),
+            issuer,
+        };
+        writeFileSync(join(this.resultsDir, `${name}.result.json`), JSON.stringify(result, null, 2));
+        if (outcome.ok) {
+            this.opts.store.logEvent("command_executed", null, { command, file: result.file, issuer });
+        }
+        else {
+            this.opts.store.logEvent("command_rejected", null, {
+                command,
+                file: result.file,
+                issuer,
+                reason: outcome.reason,
+            });
+        }
+        if (loud)
+            this.log(`[commands] REJECTED ${result.file} (${command ?? "?"}): ${outcome.reason ?? "unknown reason"}`);
+        // A parse failure is an observation, not a settled delivery: a slow
+        // writer may complete after eager retries. Keep both session and operator
+        // files eligible, even when metadata did not advance between observations.
+        if (unsettled)
+            return result;
+        // Make sure a daemon restart cannot re-execute the file: session dirs
+        // archive it into processed/; the operator dir is not writable by the
+        // daemon, so the store keeps the ledger instead, keyed by this version.
+        if (version !== null) {
+            this.opts.store.markOperatorCommandHandled(version, result.file);
+        }
+        else {
+            let atPath = null;
+            try {
+                atPath = readFileSync(path, "utf8");
+            }
+            catch {
+                /* gone — nothing to archive or to run */
+            }
+            if (readText !== null && atPath !== null && atPath !== readText) {
+                // A different command took this name while this one ran. It is not
+                // the file this result describes, so it is not archived under it: it
+                // is queued to run next (the watch event it raised found this one in
+                // flight, and a session dir has no periodic sweep to find it later).
+                // The same bytes written again are the same command, already run.
+                this.log(`[commands] ${result.file} was replaced while it ran — running the new one next`);
+                void this.enqueue(path);
+            }
+            else {
+                try {
+                    renameSync(path, join(this.processedDir, `${name}.json`));
+                }
+                catch (err) {
+                    // A vanished file is fine; any other failure leaves the source
+                    // pending, so it is logged with the path and cause.
+                    if (err.code !== "ENOENT")
+                        this.log(`[commands] could not archive ${path}: ${err.code ?? err.message}`);
+                }
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=commands.js.map