@telora/daemon 0.22.245 → 0.22.290

package/dist/completion/stall-escalations/human-only-act.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Filing-boundary classifier: does an escalation's stated content name an act
+ * only a HUMAN can perform?
+ *
+ * A filing may claim a human-owning disposition (needs_operator, external_wait)
+ * only when it names what a human uniquely supplies -- one of four categories:
+ *
+ *  1. AUTHORITY the machine lacks (an approval / sign-off / credential a human
+ *     alone holds).
+ *  2. INFORMATION not in the system (a decision or answer only the human has,
+ *     not recoverable from the repo or the DB).
+ *  3. A JUDGMENT about intent (scope / priority / direction / what to build) --
+ *     the `statedCauseNeedsIntent` case, one facet of four.
+ *  4. A PHYSICAL act (hardware, on-site, an external console no execution
+ *     surface reaches).
+ *
+ * A filing whose description alone lets a human resolve it by pasting it into an
+ * agent session names NONE of these -- the human would act as a message bus, not
+ * a regulator. Such a filing must not claim a human-owning disposition.
+ *
+ * The predicate is intentionally conservative on the POSITIVE side: it fires
+ * only on explicit evidence of a human-only act, mirroring `statedCauseNeedsIntent`
+ * (absent evidence -> machine ownership). Routing a genuinely human-owned filing
+ * to the machine lane once -- where a capable resolver either clears it or the
+ * agent-resolvable hand-off sweep gives it to the routing decider agent -- is a
+ * recoverable miss; admitting paste-resolvable junk into the human inbox on a
+ * vague match is the failure this classifier exists to stop.
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/stall-escalations/human-only-act.ts).
+ */
+/**
+ * Category 3: a JUDGMENT about WHAT gets built (scope / intent / priority /
+ * product or design direction). This is the `statedCauseNeedsIntent`
+ * predicate, kept verbatim so the demotion classifier's behavior does not
+ * shift.
+ */
+export declare function namesIntentJudgment(text: string | undefined): boolean;
+/**
+ * Whether the given text names an act ONLY a human/operator can perform -- the
+ * union of the five categories above. Callers at the filing boundary combine the
+ * escalation's description + helpNeeded and pass the result: a human-owning
+ * disposition is admissible only when this returns true.
+ */
+export declare function namesHumanOnlyAct(text: string | undefined): boolean;
+//# sourceMappingURL=human-only-act.d.ts.map

package/dist/completion/stall-escalations/human-only-act.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-only-act.d.ts","sourceRoot":"","sources":["../../../src/completion/stall-escalations/human-only-act.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKrE;AA+BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAUnE"}

package/dist/completion/stall-escalations/human-only-act.js

@@ -0,0 +1,80 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/completion/stall-escalations/human-only-act.test.ts
+// PINNED-BY-END
+/**
+ * Filing-boundary classifier: does an escalation's stated content name an act
+ * only a HUMAN can perform?
+ *
+ * A filing may claim a human-owning disposition (needs_operator, external_wait)
+ * only when it names what a human uniquely supplies -- one of four categories:
+ *
+ *  1. AUTHORITY the machine lacks (an approval / sign-off / credential a human
+ *     alone holds).
+ *  2. INFORMATION not in the system (a decision or answer only the human has,
+ *     not recoverable from the repo or the DB).
+ *  3. A JUDGMENT about intent (scope / priority / direction / what to build) --
+ *     the `statedCauseNeedsIntent` case, one facet of four.
+ *  4. A PHYSICAL act (hardware, on-site, an external console no execution
+ *     surface reaches).
+ *
+ * A filing whose description alone lets a human resolve it by pasting it into an
+ * agent session names NONE of these -- the human would act as a message bus, not
+ * a regulator. Such a filing must not claim a human-owning disposition.
+ *
+ * The predicate is intentionally conservative on the POSITIVE side: it fires
+ * only on explicit evidence of a human-only act, mirroring `statedCauseNeedsIntent`
+ * (absent evidence -> machine ownership). Routing a genuinely human-owned filing
+ * to the machine lane once -- where a capable resolver either clears it or the
+ * agent-resolvable hand-off sweep gives it to the routing decider agent -- is a
+ * recoverable miss; admitting paste-resolvable junk into the human inbox on a
+ * vague match is the failure this classifier exists to stop.
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/stall-escalations/human-only-act.ts).
+ */
+/**
+ * Category 3: a JUDGMENT about WHAT gets built (scope / intent / priority /
+ * product or design direction). This is the `statedCauseNeedsIntent`
+ * predicate, kept verbatim so the demotion classifier's behavior does not
+ * shift.
+ */
+export function namesIntentJudgment(text) {
+    if (!text)
+        return false;
+    return /\b(re-?scope|rescoping|requirement|intent|priorit|product decision|design decision|what to build|change (?:what|the scope)|which .{0,40}?(?:should|to build))\b/i.test(text);
+}
+/** Category 1: authority / permission / a credential only a human holds. */
+const AUTHORITY_RE = /\b(approv\w*|sign-?off|authoriz\w*|permission|grant\s+\w*\s*access|credential|access\s+token|password|passphrase|secret\b|budget\s+approv\w*|legal\s+review|compliance\s+(?:review|sign))\b/i;
+/** Category 4: a PHYSICAL act / on-site / an external console no agent can reach. */
+const PHYSICAL_RE = /\b(physical\w*|on-?site|hardware|data\s?cent\w*|power\s?cycle|unplug|re-?plug|reboot\s+the\s+\w+|rack\b|cabl\w*|press\s+the\s+\w+\s+button|swap\s+the\s+\w+\s+(?:drive|disk|card|module))\b/i;
+/** External third party the system cannot act on directly (pairs with external_wait). */
+const EXTERNAL_PARTY_RE = /\b(third[-\s]?party|vendor\b|provider['’]?s?\s+(?:support|console|side)|support\s+ticket|reach\s+out\s+to|contact\s+(?:the\s+)?\w+\s+(?:team|support|provider)|escalate\s+to\s+\w+\s+support)\b/i;
+/** Category 2: information/decision only the human holds (not in repo or DB). */
+const HUMAN_INFO_RE = /\b(only\s+(?:you|a\s+human)\s+\w+|human\s+(?:decision|judg(?:e)?ment|input)|business\s+decision|stakeholder\s+\w+|needs?\s+(?:a\s+)?(?:human\s+)?decision)\b/i;
+/**
+ * Category 5 (operator authority over the running system): operation of the live
+ * daemon, its verify gate, or a delivery's workflow wiring -- state a sandboxed
+ * worktree agent cannot reach. This is what the DAEMON's own structural filings
+ * name (a gate-stuck delivery's gate_state, a daemon-loop that reports success
+ * without advancing status, a delivery with no workflow stage). It is a facet of
+ * "authority the machine lacks", scoped to the operator's control plane, so those
+ * genuinely operator-owned filings pass the human-only-act test rather than being
+ * mis-downgraded into a machine lane that cannot operate the daemon.
+ */
+const OPERATOR_DOMAIN_RE = /\b(gate[_\s-]?state|verify\s+gate|gate-?stuck|daemon[-\s]?loop|workflow\s+stage|execution_status)\b/i;
+/**
+ * Whether the given text names an act ONLY a human/operator can perform -- the
+ * union of the five categories above. Callers at the filing boundary combine the
+ * escalation's description + helpNeeded and pass the result: a human-owning
+ * disposition is admissible only when this returns true.
+ */
+export function namesHumanOnlyAct(text) {
+    if (!text)
+        return false;
+    return (namesIntentJudgment(text) ||
+        AUTHORITY_RE.test(text) ||
+        PHYSICAL_RE.test(text) ||
+        EXTERNAL_PARTY_RE.test(text) ||
+        HUMAN_INFO_RE.test(text) ||
+        OPERATOR_DOMAIN_RE.test(text));
+}
+//# sourceMappingURL=human-only-act.js.map

package/dist/completion/stall-escalations/human-only-act.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-only-act.js","sourceRoot":"","sources":["../../../src/completion/stall-escalations/human-only-act.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,qFAAqF;AACrF,gBAAgB;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAwB;IAC1D,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,OAAO,kKAAkK,CAAC,IAAI,CAC5K,IAAI,CACL,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,YAAY,GAChB,8LAA8L,CAAC;AAEjM,qFAAqF;AACrF,MAAM,WAAW,GACf,8LAA8L,CAAC;AAEjM,yFAAyF;AACzF,MAAM,iBAAiB,GACrB,kMAAkM,CAAC;AAErM,iFAAiF;AACjF,MAAM,aAAa,GACjB,+JAA+J,CAAC;AAElK;;;;;;;;;GASG;AACH,MAAM,kBAAkB,GACtB,sGAAsG,CAAC;AAEzG;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACxD,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,OAAO,CACL,mBAAmB,CAAC,IAAI,CAAC;QACzB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;QACvB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QACtB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;QAC5B,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;QACxB,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAC9B,CAAC;AACJ,CAAC"}

package/dist/completion/stall-escalations/machine-remediable-demotion.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Evidence-driven demotion of a stall filing back to the machine lane.
+ *
+ * The agent_resolvable PROMOTION sweep (supervision/agent-resolvable-promotion.ts)
+ * moves ownership ONE way -- machine -> human on open-age. Without a return path
+ * a filing that a human took but that is actually machine-remediable could only
+ * ratchet toward the human. This is the inverse: an OPEN needs_intent team_failure
+ * whose recorded evidence shows a machine-remediable cause is returned to the
+ * machine (disposition agent_resolvable), where the agent-resolvable transport
+ * rides it into the next spawn.
+ *
+ * Evidence = the SAME classifier the filing path uses (statedCauseNeedsIntent).
+ * A team_failure-kind row disposed needs_intent is filed that way ONLY when a
+ * human-decision cause matched, so a row here whose recorded statedCause is NOT a
+ * human decision (a row filed before that classifier, or a misroute) is
+ * demotable; a row whose
+ * cause IS a genuine build-changing decision is left with the human. Gate-stuck
+ * filings are kind daemon_gate_stuck (needs_operator), never team_failure, so they
+ * are excluded by construction -- an operator-owned hold is never demoted.
+ *
+ * Deploy-safe like the promotion: escalation_update cannot rewrite disposition
+ * without an edge deploy, so a demotion RESOLVES the source needs_intent row and
+ * REFILES the same content as an agent_resolvable escalation (idempotent on a
+ * cause key derived from the source id). Best-effort per row; never throws.
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/stall-escalations/machine-remediable-demotion.ts).
+ */
+import { type EscalationResolutionClass } from '@telora/daemon-core';
+import type { DemotableTeamFailureItem } from '../../queries/escalations/escalation-consumption.js';
+import type { FileEscalationIdempotentParams, FileEscalationIdempotentResult } from '../../supervision/escalation-suppression.js';
+import { type MachineLaneMisRoute } from '../../supervision/routing-quality.js';
+/** escalation_kind preserved on a demoted (formerly needs_intent) team_failure. */
+export declare const MACHINE_REMEDIABLE_DEMOTED_KIND = "team_failure";
+/** The cause key that makes a demotion refile idempotent (one per source filing). */
+export declare function machineRemediableDemotionCauseKey(originalEscalationId: string): string;
+/**
+ * Pure: split open needs_intent team_failures into the ones a HUMAN still owns
+ * (their recorded cause names a build-changing decision) and the ones to DEMOTE
+ * (no human-decision cause -> machine-remediable). Exported for direct testing.
+ */
+export declare function partitionDemotable(items: readonly DemotableTeamFailureItem[]): {
+    keep: DemotableTeamFailureItem[];
+    demote: DemotableTeamFailureItem[];
+};
+/**
+ * Pure: build the agent_resolvable refile params for a needs_intent filing whose
+ * evidence shows a machine-remediable cause. Preserves the original description +
+ * kind so the incoming team sees the full context; anchored to the focus when one
+ * is present.
+ */
+export declare function buildDemotionRefileParams(item: DemotableTeamFailureItem, ctx: {
+    organizationId: string;
+    focusId?: string;
+    productId?: string;
+}): FileEscalationIdempotentParams;
+/** Counts a single demotion sweep returns (for tick logging). */
+export interface MachineRemediableDemotionCounts {
+    scanned: number;
+    demoted: number;
+    /**
+     * Machine-remediable filings that were NOT demoted this cycle because the
+     * measured machine-lane mis-route rate was over the ceiling (the lane is not
+     * clearing what it is handed, so more was withheld from it). Zero in the normal
+     * case; > 0 is the feedback firing.
+     */
+    held: number;
+}
+/** Injected IO for the demotion sweep; production binds it at the composition root (composition/escalation-lane-context.ts). */
+export interface MachineRemediableDemotionDeps {
+    listOpenDemotable: () => Promise<DemotableTeamFailureItem[]>;
+    /** Resolve the source row, recording the resolver class (a demotion refile is 'auto_swept'). */
+    markResolved: (id: string, resolutionClass: EscalationResolutionClass, notes?: string) => Promise<void>;
+    file: (params: FileEscalationIdempotentParams) => Promise<FileEscalationIdempotentResult>;
+    /** Live machine-lane mis-route measurement -- the routing-quality feedback signal. */
+    measureMisRoute: () => Promise<MachineLaneMisRoute>;
+    /** Ceiling above which demotion holds (the lane is mis-routing). */
+    misRouteCeiling: number;
+    /** Minimum judged rows before the rate is trusted to hold. */
+    minSample: number;
+}
+/**
+ * Sweep the org's OPEN needs_intent team_failures and return ownership to the
+ * machine for every one whose recorded evidence is machine-remediable: refile the
+ * same content as agent_resolvable, then resolve the source needs_intent row.
+ * Idempotent (shared cause key + source resolve) and best-effort per filing -- a
+ * failure is logged and the source left open for the next sweep, never thrown, so
+ * one bad row never aborts the sweep. Spawn-independent by design: a needs_intent
+ * team_failure BLOCKS the respawn (TEL-2 keeps human-owned holds blocking), so the
+ * demotion cannot ride a spawn -- it must run from this org loop.
+ */
+export declare function sweepMachineRemediableDemotions(d: MachineRemediableDemotionDeps): Promise<MachineRemediableDemotionCounts>;
+//# sourceMappingURL=machine-remediable-demotion.d.ts.map

package/dist/completion/stall-escalations/machine-remediable-demotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-remediable-demotion.d.ts","sourceRoot":"","sources":["../../../src/completion/stall-escalations/machine-remediable-demotion.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAA+C,KAAK,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAClH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qDAAqD,CAAC;AACpG,OAAO,KAAK,EACV,8BAA8B,EAC9B,8BAA8B,EAC/B,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAiC,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAM/G,mFAAmF;AACnF,eAAO,MAAM,+BAA+B,iBAAiB,CAAC;AAE9D,qFAAqF;AACrF,wBAAgB,iCAAiC,CAAC,oBAAoB,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,wBAAwB,EAAE,GACzC;IAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC;IAAC,MAAM,EAAE,wBAAwB,EAAE,CAAA;CAAE,CAW1E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,wBAAwB,EAC9B,GAAG,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,8BAA8B,CAmChC;AAED,iEAAiE;AACjE,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gIAAgI;AAChI,MAAM,WAAW,6BAA6B;IAC5C,iBAAiB,EAAE,MAAM,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAAC;IAC7D,gGAAgG;IAChG,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,yBAAyB,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxG,IAAI,EAAE,CAAC,MAAM,EAAE,8BAA8B,KAAK,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC1F,sFAAsF;IACtF,eAAe,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACpD,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,+BAA+B,CACnD,CAAC,EAAE,6BAA6B,GAC/B,OAAO,CAAC,+BAA+B,CAAC,CAiE1C"}

package/dist/completion/stall-escalations/machine-remediable-demotion.js

@@ -0,0 +1,165 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/completion/stall-escalations/machine-remediable-demotion.test.ts,
+//   packages/daemon/src/integration/resolution-class-routing-flow.test.ts
+// PINNED-BY-END
+/**
+ * Evidence-driven demotion of a stall filing back to the machine lane.
+ *
+ * The agent_resolvable PROMOTION sweep (supervision/agent-resolvable-promotion.ts)
+ * moves ownership ONE way -- machine -> human on open-age. Without a return path
+ * a filing that a human took but that is actually machine-remediable could only
+ * ratchet toward the human. This is the inverse: an OPEN needs_intent team_failure
+ * whose recorded evidence shows a machine-remediable cause is returned to the
+ * machine (disposition agent_resolvable), where the agent-resolvable transport
+ * rides it into the next spawn.
+ *
+ * Evidence = the SAME classifier the filing path uses (statedCauseNeedsIntent).
+ * A team_failure-kind row disposed needs_intent is filed that way ONLY when a
+ * human-decision cause matched, so a row here whose recorded statedCause is NOT a
+ * human decision (a row filed before that classifier, or a misroute) is
+ * demotable; a row whose
+ * cause IS a genuine build-changing decision is left with the human. Gate-stuck
+ * filings are kind daemon_gate_stuck (needs_operator), never team_failure, so they
+ * are excluded by construction -- an operator-owned hold is never demoted.
+ *
+ * Deploy-safe like the promotion: escalation_update cannot rewrite disposition
+ * without an edge deploy, so a demotion RESOLVES the source needs_intent row and
+ * REFILES the same content as an agent_resolvable escalation (idempotent on a
+ * cause key derived from the source id). Best-effort per row; never throws.
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/stall-escalations/machine-remediable-demotion.ts).
+ */
+import { ESCALATION_REASONS, ESCALATION_DISPOSITIONS } from '@telora/daemon-core';
+import { computeCauseKey } from '../../queries/escalations/cause-key.js';
+import { shouldHoldDemotionForMisRoute } from '../../supervision/routing-quality.js';
+import { statedCauseNeedsIntent } from './event-escalations.js';
+import { createLogger } from '../../log/daemon-log.js';
+const log = createLogger({ module: 'escalations' });
+/** escalation_kind preserved on a demoted (formerly needs_intent) team_failure. */
+export const MACHINE_REMEDIABLE_DEMOTED_KIND = 'team_failure';
+/** The cause key that makes a demotion refile idempotent (one per source filing). */
+export function machineRemediableDemotionCauseKey(originalEscalationId) {
+    return computeCauseKey('team_failure_demoted', { escalationId: originalEscalationId });
+}
+/**
+ * Pure: split open needs_intent team_failures into the ones a HUMAN still owns
+ * (their recorded cause names a build-changing decision) and the ones to DEMOTE
+ * (no human-decision cause -> machine-remediable). Exported for direct testing.
+ */
+export function partitionDemotable(items) {
+    const keep = [];
+    const demote = [];
+    for (const item of items) {
+        if (statedCauseNeedsIntent(item.statedCause)) {
+            keep.push(item); // a genuine human decision -- leave it with the human
+        }
+        else {
+            demote.push(item); // no human-decision evidence -- return to the machine
+        }
+    }
+    return { keep, demote };
+}
+/**
+ * Pure: build the agent_resolvable refile params for a needs_intent filing whose
+ * evidence shows a machine-remediable cause. Preserves the original description +
+ * kind so the incoming team sees the full context; anchored to the focus when one
+ * is present.
+ */
+export function buildDemotionRefileParams(item, ctx) {
+    return {
+        causeKey: machineRemediableDemotionCauseKey(item.id),
+        organizationId: ctx.organizationId,
+        issueId: null,
+        reasonType: ESCALATION_REASONS.BLOCKED_BY_EXTERNAL,
+        // Evidence shows the cause is machine-remediable -> return it to the machine
+        // lane. The agent-resolvable transport rides it into the next coding spawn;
+        // if it survives, the hand-off sweep gives it to the routing decider agent,
+        // which alone can make it human-facing.
+        disposition: ESCALATION_DISPOSITIONS.AGENT_RESOLVABLE,
+        anchor: ctx.focusId ? { focusId: ctx.focusId } : {},
+        ...(ctx.productId ? { productId: ctx.productId } : {}),
+        escalationKind: MACHINE_REMEDIABLE_DEMOTED_KIND,
+        description: `A no-progress stall filed to the intent owner has been RETURNED to the ` +
+            `machine: its recorded cause names no build-changing decision, so it is ` +
+            `machine-remediable and rides into the focus's next coding spawn.\n\n` +
+            `**Demoted from:** needs_intent (team_failure)\n` +
+            `**Original filing:** ${item.id}\n\n` +
+            `${item.description}`,
+        whatWasTried: `The stall was re-classified from its own recorded stated cause; no human ` +
+            `decision is required, so ownership returned to the machine (needs_intent -> ` +
+            `agent_resolvable).`,
+        helpNeeded: `None from a human yet -- the incoming coding team will attempt this. If it ` +
+            `survives the agent-resolvable window it is handed to the routing decider agent, ` +
+            `which alone can make it human-facing.`,
+        metadata: {
+            cause: MACHINE_REMEDIABLE_DEMOTED_KIND,
+            demotedFrom: 'needs_intent',
+            originalEscalationId: item.id,
+        },
+    };
+}
+/**
+ * Sweep the org's OPEN needs_intent team_failures and return ownership to the
+ * machine for every one whose recorded evidence is machine-remediable: refile the
+ * same content as agent_resolvable, then resolve the source needs_intent row.
+ * Idempotent (shared cause key + source resolve) and best-effort per filing -- a
+ * failure is logged and the source left open for the next sweep, never thrown, so
+ * one bad row never aborts the sweep. Spawn-independent by design: a needs_intent
+ * team_failure BLOCKS the respawn (TEL-2 keeps human-owned holds blocking), so the
+ * demotion cannot ride a spawn -- it must run from this org loop.
+ */
+export async function sweepMachineRemediableDemotions(d) {
+    const open = await d.listOpenDemotable();
+    const { demote } = partitionDemotable(open);
+    // Routing-quality feedback: measure the machine lane's live mis-route rate and,
+    // if it is over the ceiling on sufficient evidence, HOLD -- do not return more
+    // filings to a lane that is not clearing what it already holds. The measured
+    // rate thereby feeds back into how these filings are classified (kept with the
+    // human vs demoted to the machine). Best-effort: a measurement failure never
+    // blocks the sweep -- it proceeds as if unmeasured.
+    let misRoute = { judged: 0, misRouted: 0, rate: 0 };
+    try {
+        misRoute = await d.measureMisRoute();
+    }
+    catch (err) {
+        log.warn(`[escalations] demotion mis-route measure failed (proceeding unmeasured): ${err.message}`);
+    }
+    if (demote.length > 0 && shouldHoldDemotionForMisRoute(misRoute, { ceiling: d.misRouteCeiling, minSample: d.minSample })) {
+        log.info(`[machine-remediable-demotion] HOLDING ${demote.length} demotion(s): machine-lane mis-route ` +
+            `rate ${misRoute.rate.toFixed(2)} > ceiling ${d.misRouteCeiling} over ${misRoute.judged} judged ` +
+            `rows -- the machine lane is not clearing what it holds, so more is withheld from it this cycle`);
+        return { scanned: open.length, demoted: 0, held: demote.length };
+    }
+    let demoted = 0;
+    for (const item of demote) {
+        if (!item.organizationId) {
+            log.warn(`[escalations] needs_intent team_failure ${item.id} is machine-remediable but ` +
+                `lacks an org anchor; cannot refile (skipping)`);
+            continue;
+        }
+        const ctx = {
+            organizationId: item.organizationId,
+            ...(item.focusId ? { focusId: item.focusId } : {}),
+            ...(item.productId ? { productId: item.productId } : {}),
+        };
+        try {
+            const result = await d.file(buildDemotionRefileParams(item, ctx));
+            // Only retire the source once the agent_resolvable refile is in place (filed
+            // OR already suppressed by a prior demotion) -- never resolve without a
+            // landing spot, which would drop the signal entirely.
+            if (result.filed || result.suppressed) {
+                await d.markResolved(item.id, 'auto_swept', `Returned to the machine: the recorded cause is machine-remediable, so ` +
+                    `ownership was demoted needs_intent -> agent_resolvable.`);
+                demoted++;
+                log.info(`[escalations] Demoted needs_intent team_failure ${item.id} to agent_resolvable ` +
+                    `(focus ${item.focusId ?? '<none>'})`);
+            }
+        }
+        catch (err) {
+            log.warn(`[escalations] Failed to demote needs_intent team_failure ${item.id}: ${err.message}`);
+            // Left open; the next sweep retries.
+        }
+    }
+    return { scanned: open.length, demoted, held: 0 };
+}
+//# sourceMappingURL=machine-remediable-demotion.js.map

package/dist/completion/stall-escalations/machine-remediable-demotion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-remediable-demotion.js","sourceRoot":"","sources":["../../../src/completion/stall-escalations/machine-remediable-demotion.ts"],"names":[],"mappings":"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"}

package/dist/completion/state-cascade/review-approved-head-gate.d.ts

@@ -0,0 +1,54 @@
+import { type FocusOwnDeltaGit } from '../../git/focus-own-delta.js';
+/** The focus head a review would cover, and the commit its current approval judged. */
+export interface ReviewHeadApproval {
+    /** The focus branch tip, null when it cannot be resolved. */
+    headSha: string | null;
+    /** The commit the newest current approval judged, null when none (or not read). */
+    approvedSha: string | null;
+}
+/** Which focus branch to resolve, and where its approvals are recorded. */
+export interface ReviewHeadApprovalTarget {
+    productId: string;
+    focusId: string;
+    /** Pinned focus branch identity (product_focuses.branch_name), or null. */
+    branchName: string | null;
+    /** Product repo path -- the branch ref lives in its git dir (worktrees share it). */
+    repoPath: string;
+    /**
+     * The integration branch. When given, a head that only adds OTHER foci's commits
+     * on top of the approved commit is read as that approved commit (module doc).
+     */
+    integrationBranch?: string;
+}
+/** Injected reads; production binds git, the product-api and the auto-approval records (composition/state-cascade-context.ts). */
+export interface ReviewHeadApprovalReadDeps {
+    resolveRef: (repoPath: string, ref: string) => string | null;
+    /** Throws when the review history cannot be read. */
+    readApprovedReviewSha: (target: ReviewHeadApprovalTarget) => Promise<string | null>;
+    /** Whether `head` adds nothing of the focus's own on top of `approved` (git/focus-own-delta.ts). Absent: never. */
+    addsNoOwnWork?: (target: ReviewHeadApprovalTarget & {
+        integrationBranch: string;
+    }, approved: string, head: string) => Promise<boolean>;
+}
+/**
+ * The production ownership proof: `repoPath` is the product checkout (its HEAD is
+ * not the focus branch), so provenance is read from the NAMED focus branch, with the
+ * focus's delivery ids from `listDeliveryIds` (the product-api in production).
+ */
+export declare function makeHeadAddsNoOwnWork(listDeliveryIds: (focusId: string) => Promise<readonly string[]>, git: FocusOwnDeltaGit): NonNullable<ReviewHeadApprovalReadDeps['addsNoOwnWork']>;
+/**
+ * Read the focus head and its current approval. The approval is read only once
+ * the head resolves (with no head there is nothing to compare, so the product-api
+ * call is skipped). Throws when the approval read throws.
+ */
+export declare function readReviewHeadApproval(target: ReviewHeadApprovalTarget, deps: ReviewHeadApprovalReadDeps): Promise<ReviewHeadApproval>;
+/** Whether the focus head is the commit its current approval already judged. Pure. */
+export declare function isHeadAlreadyApproved(read: ReviewHeadApproval): boolean;
+/**
+ * Whether checkAutoReview must decline to open the review window because the focus
+ * head is unchanged since its current approval. Logs the decline (info). Fails
+ * OPEN: an absent reader, an unknown head or approval, or a thrown read returns
+ * false (a thrown read is logged at warn).
+ */
+export declare function declinesReviewAtApprovedHead(focusId: string, read: ((focusId: string) => Promise<ReviewHeadApproval>) | undefined): Promise<boolean>;
+//# sourceMappingURL=review-approved-head-gate.d.ts.map

package/dist/completion/state-cascade/review-approved-head-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-approved-head-gate.d.ts","sourceRoot":"","sources":["../../../src/completion/state-cascade/review-approved-head-gate.ts"],"names":[],"mappings":"AAqDA,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAK7F,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mFAAmF;IACnF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,kIAAkI;AAClI,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC7D,qDAAqD;IACrD,qBAAqB,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpF,mHAAmH;IACnH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,GAAG;QAAE,iBAAiB,EAAE,MAAM,CAAA;KAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxI;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,EAChE,GAAG,EAAE,gBAAgB,GACpB,WAAW,CAAC,0BAA0B,CAAC,eAAe,CAAC,CAAC,CAK1D;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAmB7B;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAEvE;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,SAAS,GACnE,OAAO,CAAC,OAAO,CAAC,CAmBlB"}

package/dist/completion/state-cascade/review-approved-head-gate.js

@@ -0,0 +1,116 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/completion/state-cascade/review-approved-head-gate.test.ts,
+//   packages/daemon/src/composition/review-holds-context.test.ts,
+//   packages/daemon/src/integration/approved-head-gate-failure-respawn-regression.test.ts,
+//   packages/daemon/src/integration/approved-head-hold-release-regression.test.ts,
+//   packages/daemon/src/integration/fully-merged-focus-sibling-red-scenario.test.ts,
+//   packages/daemon/src/integration/shortfall-ruling-disposes-proposals-regression.test.ts,
+//   packages/daemon/src/integration/standing-approval-release-regression.test.ts
+// PINNED-BY-END
+/**
+ * Review runs once per distinct focus head: an unchanged head since the focus's
+ * current approval draws no new review window.
+ *
+ * checkAutoReview (state-cascade.ts) opens the review window when a focus
+ * converges on verify. Its only in-memory backoff is a signature over the delivery
+ * aggregate (status, updated_at, merge commit, git state) -- and a verify delivery
+ * held by a repeating shortfall has its gate_state rewritten every pass, which
+ * bumps updated_at and invalidates that signature, so without this gate each
+ * rewrite would re-open the window at the SAME focus head and spawn a review
+ * team that approves the same commit again.
+ *
+ * The approval that makes a re-review pointless is the one the merge gate already
+ * reads (queries/focus-review/focus-review-approval.ts readLatestApprovedReviewSha): the newest
+ * CURRENT approval -- an approved focus_reviews row or a recorded clean
+ * full-coverage auto-approval (merge/review-auto-approval-record.ts) -- which
+ * a newer gaps_found review of the same commit revokes. The head is the focus
+ * branch tip a review spawn would pin as its coverage anchor (focus-executor.ts
+ * captureReviewSpawnCoverage resolves the branch ref; a review spawn skips the
+ * rebase, and worktrees share the repo's refs).
+ *
+ * So the window is declined only when the head and the current approval are both
+ * KNOWN and name the same commit. A new commit on the focus, a newer gaps_found at
+ * that commit (approval revoked -> null), or no approval at all leaves review
+ * eligible.
+ *
+ * FAILS OPEN: an unresolvable head, an unreadable review history, or a thrown read
+ * lets the window open. A missed skip costs one review pass; a false skip would
+ * strand a verify delivery that still needs its verdict.
+ *
+ * NO SAME-HEAD EXCEPTION: a verify delivery that becomes closable at the approved
+ * head with no new commit (a ruling released its shortfall park and verify then
+ * passed) does NOT re-open the window -- that would re-run review and stamp
+ * another approval of the unchanged commit. It converges on the STANDING approval instead
+ * (completion/state-cascade/standing-approval-convergence.ts), through the review exit's own
+ * holds, with no review run and no approval written.
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/state-cascade/review-approved-head-gate.ts).
+ *
+ * @module completion/state-cascade/review-approved-head-gate
+ */
+import { sameCommit } from '../../queries/focus-review/focus-review-approval.js';
+import { isForeignOnlyExtension } from '../../git/focus-own-delta.js';
+import { createLogger } from '../../log/daemon-log.js';
+const log = createLogger({ module: 'state-cascade' });
+/**
+ * The production ownership proof: `repoPath` is the product checkout (its HEAD is
+ * not the focus branch), so provenance is read from the NAMED focus branch, with the
+ * focus's delivery ids from `listDeliveryIds` (the product-api in production).
+ */
+export function makeHeadAddsNoOwnWork(listDeliveryIds, git) {
+    return async (target, approved, head) => isForeignOnlyExtension(target.repoPath, target.integrationBranch, approved, head, new Set(await listDeliveryIds(target.focusId)), target.branchName ? { git, focusBranch: target.branchName } : { git });
+}
+/**
+ * Read the focus head and its current approval. The approval is read only once
+ * the head resolves (with no head there is nothing to compare, so the product-api
+ * call is skipped). Throws when the approval read throws.
+ */
+export async function readReviewHeadApproval(target, deps) {
+    const headSha = target.branchName ? deps.resolveRef(target.repoPath, target.branchName) : null;
+    if (!headSha)
+        return { headSha: null, approvedSha: null };
+    const approvedSha = await deps.readApprovedReviewSha(target);
+    const { integrationBranch } = target;
+    if (approvedSha && integrationBranch && deps.addsNoOwnWork && !sameCommit(headSha, approvedSha)) {
+        // A focus whose commits are all on integration, moved past its approved commit
+        // only by other foci's commits, has no own work to review: its OWN head is the
+        // approved commit. Unprovable (or a failed read) keeps the branch tip.
+        const noOwnWork = await deps.addsNoOwnWork({ ...target, integrationBranch }, approvedSha, headSha).catch(() => false);
+        if (noOwnWork) {
+            log.info(`[state-cascade] Focus ${target.focusId}: head ${headSha.slice(0, 12)} adds only other foci's commits (already on ` +
+                `integration) to its approved commit ${approvedSha.slice(0, 12)} -- read as that approved head, no review over them`);
+            return { headSha: approvedSha, approvedSha };
+        }
+    }
+    return { headSha, approvedSha };
+}
+/** Whether the focus head is the commit its current approval already judged. Pure. */
+export function isHeadAlreadyApproved(read) {
+    return read.headSha !== null && read.approvedSha !== null && sameCommit(read.headSha, read.approvedSha);
+}
+/**
+ * Whether checkAutoReview must decline to open the review window because the focus
+ * head is unchanged since its current approval. Logs the decline (info). Fails
+ * OPEN: an absent reader, an unknown head or approval, or a thrown read returns
+ * false (a thrown read is logged at warn).
+ */
+export async function declinesReviewAtApprovedHead(focusId, read) {
+    if (!read)
+        return false;
+    let result;
+    try {
+        result = await read(focusId);
+    }
+    catch (err) {
+        log.warn(`[state-cascade] Could not read the approved review head for focus ${focusId}; ` +
+            `opening the review window as before: ${err.message}`);
+        return false;
+    }
+    if (!isHeadAlreadyApproved(result))
+        return false;
+    log.info(`[state-cascade] Not opening a review window on focus ${focusId}: its head ` +
+        `${(result.headSha ?? '').slice(0, 12)} is the commit its current approval already judged ` +
+        `-- review runs once per distinct focus head.`);
+    return true;
+}
+//# sourceMappingURL=review-approved-head-gate.js.map

package/dist/completion/state-cascade/review-approved-head-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-approved-head-gate.js","sourceRoot":"","sources":["../../../src/completion/state-cascade/review-approved-head-gate.ts"],"names":[],"mappings":"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"}