patchwork-os 1.2.0-beta.2.canary.633 → 1.2.0-beta.2.canary.635

package/dist/butler/errandOutcomeGrader.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Butler errand outcome grader — "did the operator keep it?"
+ *
+ * A Butler errand's artifact is usually a task in a tracker, not a GitHub
+ * issue, so `classifyIssueDisposition` (outcomeStore.ts) does not apply. This
+ * is its sibling for artifacts whose only honest signal is what the operator
+ * subsequently did with the thing.
+ *
+ * ## The model
+ *
+ *   completed        → confirmed   the operator acted on it. Real positive.
+ *   deleted          → junk        the operator threw it away. Real negative.
+ *   open + stale     → junk        left untouched past the staleness horizon.
+ *   open + recent    → WITHHELD    no signal yet. Not evidence in EITHER
+ *                                  direction.
+ *
+ * ## Why "open + recent" must withhold rather than pass
+ *
+ * This is the single load-bearing rule, and it is the one a reasonable person
+ * gets wrong. An errand that nobody has deleted looks like a success and is
+ * not one: the operator may simply not have looked. Folding it as good is
+ * trust-by-neglect, the exact defect closed three times already in this
+ * subsystem (#1064, #1318/#1319, #1320, #1322) — each time by making absence
+ * of a negative stop counting as a positive.
+ *
+ * So the grader has no "default to good" branch at all. Every path that is not
+ * a POSITIVE ACT by the operator returns `unknown`, which the fold withholds.
+ *
+ * ## Why stale → junk rather than unknown
+ *
+ * Asymmetric on purpose. `unknown` is the right answer while the operator
+ * might still act; it is the wrong answer once enough time has passed that
+ * not-acting IS the answer. Leaving it `unknown` forever would let a worker
+ * that files things nobody ever touches sit permanently un-judged instead of
+ * accumulating the negative it has earned. The horizon is explicit and long
+ * (default 14 days) precisely because it converts silence into a negative.
+ *
+ * ## No model in the loop
+ *
+ * Pure function of observed state and two timestamps. A prior LLM judge in
+ * this repo flipped verdicts between runs on identical inputs, which makes the
+ * trust ledger unreproducible — and a trust ledger you cannot replay is not
+ * evidence, it is an opinion with a timestamp.
+ */
+import type { OutcomeDisposition } from "../workers/outcomeStore.js";
+/** Default staleness horizon: 14 days. */
+export declare const DEFAULT_STALE_AFTER_MS: number;
+/**
+ * What we observed about the errand's artifact.
+ *
+ * Every field is optional because observation is best-effort — a connector may
+ * not report deletion at all. Absent fields must never be read as a positive:
+ * see `gradeErrandOutcome`'s ordering.
+ */
+export interface ObservedErrandArtifact {
+    /** The operator marked it done. A positive act. */
+    completed?: boolean;
+    /**
+     * The artifact is gone. A positive act in the other direction.
+     *
+     * Distinct from "we could not find it": a lookup failure must be reported as
+     * `undefined`, never as `deleted: true`. A transient API error that reads as
+     * deletion would manufacture a negative against a worker that did nothing
+     * wrong.
+     */
+    deleted?: boolean;
+    /** When the errand created the artifact. */
+    createdAt?: number;
+}
+export interface GradeOptions {
+    /** Clock. Injected so grading is reproducible in replay. */
+    now: number;
+    /** How long "open" stays `unknown` before becoming `junk`. */
+    staleAfterMs?: number;
+}
+export interface GradedOutcome {
+    disposition: OutcomeDisposition;
+    /**
+     * Why, in a form a human can check against the row. Stored alongside the
+     * disposition — a verdict whose reasoning is not recorded cannot be audited,
+     * only believed.
+     */
+    reason: "completed" | "deleted" | "stale-unactioned" | "open-recent" | "not-observed";
+}
+/**
+ * Grade one observed artifact.
+ *
+ * Ordering is deliberate: the two POSITIVE ACTS are tested first, then
+ * staleness, and everything remaining falls to `unknown`. There is no branch
+ * that reaches `confirmed` without `completed === true`.
+ */
+export declare function gradeErrandOutcome(observed: ObservedErrandArtifact, opts: GradeOptions): GradedOutcome;

package/dist/butler/errandOutcomeGrader.js

@@ -0,0 +1,79 @@
+/**
+ * Butler errand outcome grader — "did the operator keep it?"
+ *
+ * A Butler errand's artifact is usually a task in a tracker, not a GitHub
+ * issue, so `classifyIssueDisposition` (outcomeStore.ts) does not apply. This
+ * is its sibling for artifacts whose only honest signal is what the operator
+ * subsequently did with the thing.
+ *
+ * ## The model
+ *
+ *   completed        → confirmed   the operator acted on it. Real positive.
+ *   deleted          → junk        the operator threw it away. Real negative.
+ *   open + stale     → junk        left untouched past the staleness horizon.
+ *   open + recent    → WITHHELD    no signal yet. Not evidence in EITHER
+ *                                  direction.
+ *
+ * ## Why "open + recent" must withhold rather than pass
+ *
+ * This is the single load-bearing rule, and it is the one a reasonable person
+ * gets wrong. An errand that nobody has deleted looks like a success and is
+ * not one: the operator may simply not have looked. Folding it as good is
+ * trust-by-neglect, the exact defect closed three times already in this
+ * subsystem (#1064, #1318/#1319, #1320, #1322) — each time by making absence
+ * of a negative stop counting as a positive.
+ *
+ * So the grader has no "default to good" branch at all. Every path that is not
+ * a POSITIVE ACT by the operator returns `unknown`, which the fold withholds.
+ *
+ * ## Why stale → junk rather than unknown
+ *
+ * Asymmetric on purpose. `unknown` is the right answer while the operator
+ * might still act; it is the wrong answer once enough time has passed that
+ * not-acting IS the answer. Leaving it `unknown` forever would let a worker
+ * that files things nobody ever touches sit permanently un-judged instead of
+ * accumulating the negative it has earned. The horizon is explicit and long
+ * (default 14 days) precisely because it converts silence into a negative.
+ *
+ * ## No model in the loop
+ *
+ * Pure function of observed state and two timestamps. A prior LLM judge in
+ * this repo flipped verdicts between runs on identical inputs, which makes the
+ * trust ledger unreproducible — and a trust ledger you cannot replay is not
+ * evidence, it is an opinion with a timestamp.
+ */
+/** Default staleness horizon: 14 days. */
+export const DEFAULT_STALE_AFTER_MS = 14 * 24 * 60 * 60 * 1000;
+/**
+ * Grade one observed artifact.
+ *
+ * Ordering is deliberate: the two POSITIVE ACTS are tested first, then
+ * staleness, and everything remaining falls to `unknown`. There is no branch
+ * that reaches `confirmed` without `completed === true`.
+ */
+export function gradeErrandOutcome(observed, opts) {
+    // Deleted is checked BEFORE completed. A tracker can report both when an
+    // operator completes and then clears a task, and "they threw it away" is the
+    // more conservative reading of a contradictory pair — it lowers trust rather
+    // than raising it on ambiguous evidence.
+    if (observed.deleted === true) {
+        return { disposition: "junk", reason: "deleted" };
+    }
+    if (observed.completed === true) {
+        return { disposition: "confirmed", reason: "completed" };
+    }
+    // Not completed, not deleted. Everything from here is an ABSENCE, and no
+    // absence may produce `confirmed`.
+    if (observed.createdAt === undefined) {
+        // We cannot even tell how long it has been open, so we cannot tell whether
+        // silence has become meaningful. Withhold.
+        return { disposition: "unknown", reason: "not-observed" };
+    }
+    const staleAfter = opts.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    const age = opts.now - observed.createdAt;
+    if (age >= staleAfter) {
+        return { disposition: "junk", reason: "stale-unactioned" };
+    }
+    return { disposition: "unknown", reason: "open-recent" };
+}
+//# sourceMappingURL=errandOutcomeGrader.js.map

package/dist/butler/errandOutcomeGrader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errandOutcomeGrader.js","sourceRoot":"","sources":["../../src/butler/errandOutcomeGrader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,0CAA0C;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AA+C/D;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgC,EAChC,IAAkB;IAElB,yEAAyE;IACzE,6EAA6E;IAC7E,6EAA6E;IAC7E,yCAAyC;IACzC,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC3D,CAAC;IAED,yEAAyE;IACzE,mCAAmC;IACnC,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrC,2EAA2E;QAC3E,2CAA2C;QAC3C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,IAAI,sBAAsB,CAAC;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC;IAC1C,IAAI,GAAG,IAAI,UAAU,EAAE,CAAC;QACtB,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AAC3D,CAAC"}

package/dist/butler/outcomeShadowLog.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Shadow ledger for graded Butler errand outcomes.
+ *
+ * A SEPARATE file from `outcome-log.jsonl`, and that separation is the entire
+ * safety property of this phase. The trust fold reads `outcome-log.jsonl`; it
+ * does not read this file and must not be taught to. Rows here are a
+ * measurement of what the grader WOULD have said, recorded so the labelling
+ * can be checked against reality before anything moves a worker's dial.
+ *
+ * This mirrors how the autonomy gate itself was landed — `workers shadow` and
+ * `workers backtest` measured divergence for a whole campaign before the gate
+ * was allowed to decide anything — and how #1319 was flipped, against a
+ * measured delta rather than an argument. The pattern exists because the
+ * alternative has failed here repeatedly: a labelling change that looks
+ * obviously correct turns out to move real workers in ways nobody predicted,
+ * and by then it is already in the ledger the gate rests on.
+ *
+ * ## What "shadow" costs
+ *
+ * Nothing observable. No gate decision consults it, no dial reads it, and
+ * deleting the file loses only the measurement. That is the point: until
+ * someone has read these rows against the real errands they describe, the
+ * grader has not earned the right to be evidence.
+ *
+ * ## Promotion
+ *
+ * Promoting it means writing graded rows into `outcome-log.jsonl` through
+ * `OutcomeStore.upsert` — deliberately NOT implemented here. That step needs
+ * the join key to be right (`ref` = `"<tool>:<id>"`, see `actionRef.ts`) and a
+ * measured before/after on the real log, exactly as #1319 required.
+ */
+import type { OutcomeDisposition } from "../workers/outcomeStore.js";
+import type { GradedOutcome } from "./errandOutcomeGrader.js";
+/**
+ * Filename. Deliberately NOT `outcome-log.jsonl` and deliberately not in a
+ * subdirectory of it — a reader that globs the outcome log must not pick this
+ * up by accident.
+ */
+export declare const SHADOW_LOG_BASENAME = "butler_outcome_shadow.jsonl";
+export declare function shadowLogPath(override?: string): string;
+export interface ShadowOutcomeRow {
+    /**
+     * The action this grades, in `canonicalActionRef` form (`"<tool>:<id>"`).
+     * Stored so a promoted row can join to the same action the fold would —
+     * recording a grade under a key the fold cannot resolve would produce a
+     * measurement of nothing.
+     */
+    ref: string;
+    disposition: OutcomeDisposition;
+    reason: GradedOutcome["reason"];
+    /** When the grade was computed. */
+    gradedAt: number;
+    /** The recipe that filed the action, for attribution during review. */
+    recipe?: string;
+    /**
+     * Whether the fold WOULD have counted this as evidence. Derived once at
+     * write time so a reviewer reading the file does not have to re-derive the
+     * withholding rule and risk deriving it differently.
+     */
+    wouldCountAsEvidence: boolean;
+}
+/** `unknown` is withheld by the fold; the other two are evidence. */
+export declare function wouldCountAsEvidence(d: OutcomeDisposition): boolean;
+/**
+ * Append one graded row. Append-only and best-effort: this is a measurement,
+ * and a measurement must never be able to fail an errand it is observing.
+ */
+export declare function appendShadowOutcome(row: Omit<ShadowOutcomeRow, "wouldCountAsEvidence">, opts?: {
+    dir?: string;
+}): void;
+export interface ShadowSummary {
+    total: number;
+    confirmed: number;
+    junk: number;
+    unknown: number;
+    /** Rows that would have become evidence had the grader been live. */
+    wouldCount: number;
+}
+/**
+ * Summarise the shadow ledger — the number this phase exists to produce.
+ *
+ * Malformed lines are SKIPPED but counted in nothing; a half-written row from
+ * an interrupted append is not evidence of anything and must not inflate a
+ * count someone is about to make a decision on.
+ */
+export declare function summariseShadowLog(opts?: {
+    dir?: string;
+}): ShadowSummary;

package/dist/butler/outcomeShadowLog.js

@@ -0,0 +1,113 @@
+/**
+ * Shadow ledger for graded Butler errand outcomes.
+ *
+ * A SEPARATE file from `outcome-log.jsonl`, and that separation is the entire
+ * safety property of this phase. The trust fold reads `outcome-log.jsonl`; it
+ * does not read this file and must not be taught to. Rows here are a
+ * measurement of what the grader WOULD have said, recorded so the labelling
+ * can be checked against reality before anything moves a worker's dial.
+ *
+ * This mirrors how the autonomy gate itself was landed — `workers shadow` and
+ * `workers backtest` measured divergence for a whole campaign before the gate
+ * was allowed to decide anything — and how #1319 was flipped, against a
+ * measured delta rather than an argument. The pattern exists because the
+ * alternative has failed here repeatedly: a labelling change that looks
+ * obviously correct turns out to move real workers in ways nobody predicted,
+ * and by then it is already in the ledger the gate rests on.
+ *
+ * ## What "shadow" costs
+ *
+ * Nothing observable. No gate decision consults it, no dial reads it, and
+ * deleting the file loses only the measurement. That is the point: until
+ * someone has read these rows against the real errands they describe, the
+ * grader has not earned the right to be evidence.
+ *
+ * ## Promotion
+ *
+ * Promoting it means writing graded rows into `outcome-log.jsonl` through
+ * `OutcomeStore.upsert` — deliberately NOT implemented here. That step needs
+ * the join key to be right (`ref` = `"<tool>:<id>"`, see `actionRef.ts`) and a
+ * measured before/after on the real log, exactly as #1319 required.
+ */
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { patchworkHome } from "../patchworkHome.js";
+/**
+ * Filename. Deliberately NOT `outcome-log.jsonl` and deliberately not in a
+ * subdirectory of it — a reader that globs the outcome log must not pick this
+ * up by accident.
+ */
+export const SHADOW_LOG_BASENAME = "butler_outcome_shadow.jsonl";
+export function shadowLogPath(override) {
+    return path.join(override ?? patchworkHome(), SHADOW_LOG_BASENAME);
+}
+/** `unknown` is withheld by the fold; the other two are evidence. */
+export function wouldCountAsEvidence(d) {
+    return d !== "unknown";
+}
+/**
+ * Append one graded row. Append-only and best-effort: this is a measurement,
+ * and a measurement must never be able to fail an errand it is observing.
+ */
+export function appendShadowOutcome(row, opts = {}) {
+    const full = {
+        ...row,
+        wouldCountAsEvidence: wouldCountAsEvidence(row.disposition),
+    };
+    try {
+        appendFileSync(shadowLogPath(opts.dir), `${JSON.stringify(full)}\n`);
+    }
+    catch {
+        // Swallowed on purpose. See above: an unwritable shadow ledger must not
+        // turn into an errand failure.
+    }
+}
+/**
+ * Summarise the shadow ledger — the number this phase exists to produce.
+ *
+ * Malformed lines are SKIPPED but counted in nothing; a half-written row from
+ * an interrupted append is not evidence of anything and must not inflate a
+ * count someone is about to make a decision on.
+ */
+export function summariseShadowLog(opts = {}) {
+    const empty = {
+        total: 0,
+        confirmed: 0,
+        junk: 0,
+        unknown: 0,
+        wouldCount: 0,
+    };
+    const p = shadowLogPath(opts.dir);
+    if (!existsSync(p))
+        return empty;
+    let text;
+    try {
+        text = readFileSync(p, "utf-8");
+    }
+    catch {
+        return empty;
+    }
+    const out = { ...empty };
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (row.disposition !== "confirmed" &&
+            row.disposition !== "junk" &&
+            row.disposition !== "unknown") {
+            continue;
+        }
+        out.total++;
+        out[row.disposition]++;
+        if (row.wouldCountAsEvidence)
+            out.wouldCount++;
+    }
+    return out;
+}
+//# sourceMappingURL=outcomeShadowLog.js.map

package/dist/butler/outcomeShadowLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcomeShadowLog.js","sourceRoot":"","sources":["../../src/butler/outcomeShadowLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,6BAA6B,CAAC;AAEjE,MAAM,UAAU,aAAa,CAAC,QAAiB;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,aAAa,EAAE,EAAE,mBAAmB,CAAC,CAAC;AACrE,CAAC;AAwBD,qEAAqE;AACrE,MAAM,UAAU,oBAAoB,CAAC,CAAqB;IACxD,OAAO,CAAC,KAAK,SAAS,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAmD,EACnD,OAAyB,EAAE;IAE3B,MAAM,IAAI,GAAqB;QAC7B,GAAG,GAAG;QACN,oBAAoB,EAAE,oBAAoB,CAAC,GAAG,CAAC,WAAW,CAAC;KAC5D,CAAC;IACF,IAAI,CAAC;QACH,cAAc,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,+BAA+B;IACjC,CAAC;AACH,CAAC;AAWD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAyB,EAAE;IAC5D,MAAM,KAAK,GAAkB;QAC3B,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,IAAI,EAAE,CAAC;QACP,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,CAAC;KACd,CAAC;IACF,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,GAAqB,CAAC;QAC1B,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAqB,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IACE,GAAG,CAAC,WAAW,KAAK,WAAW;YAC/B,GAAG,CAAC,WAAW,KAAK,MAAM;YAC1B,GAAG,CAAC,WAAW,KAAK,SAAS,EAC7B,CAAC;YACD,SAAS;QACX,CAAC;QACD,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,oBAAoB;YAAE,GAAG,CAAC,UAAU,EAAE,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchwork-os",
-  "version": "1.2.0-beta.2.canary.633",
+  "version": "1.2.0-beta.2.canary.635",
   "description": "Your personal AI runtime, local-first. Patchwork OS gives any AI model a consistent set of tools, YAML recipes, a delegation policy with approval queue, and a durable trace memory — all on your machine, all under your policy.",
   "type": "module",
   "main": "dist/index.js",