@sweny-ai/core 0.1.189 → 0.1.191

package/dist/cli/run-answers.d.ts

@@ -41,6 +41,11 @@ export interface BuildRunAnswersInput {
     results: Map<string, NodeResult>;
     /** Secret values to redact (the same set the journal and output.md use). */
     secrets?: string[];
+    /**
+     * The key for redacted key names, asked for only when a key needs one. Default: a random key that
+     * lives only in this process (names then differ from run to run, which a diff shows as a change).
+     */
+    macKey?: () => Buffer;
 }
 /**
  * Declared fields of each successful node, deep, redacted (values and keys). A failed or skipped

package/dist/cli/run-answers.js

@@ -21,7 +21,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { redact } from "../journal.js";
+import { redact, workspaceSecretKey } from "../journal.js";
 import { writeFileNoFollow } from "../safe-file.js";
 import { RUN_HISTORY_DIR, RUN_ID_RE, listRuns } from "./run-history.js";
 export const RUN_ANSWERS_SCHEMA_VERSION = 1;
@@ -32,13 +32,56 @@ const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 // ── Build, write, read ──────────────────────────────────────────
 const has = (o, k) => Object.hasOwn(o, k);
 const sha = (s) => crypto.createHash("sha256").update(s).digest("hex");
+/** The JSON Schema types a schema declares: `type`, else implied by `properties` / `items`. */
+function declaredTypes(sch) {
+    if (typeof sch.type === "string")
+        return [sch.type];
+    if (Array.isArray(sch.type))
+        return sch.type.filter((t) => typeof t === "string");
+    if (isObj(sch.properties))
+        return ["object"];
+    if (isObj(sch.items))
+        return ["array"];
+    return undefined;
+}
+function typeMatches(value, types) {
+    return types.some((t) => {
+        switch (t) {
+            case "string":
+                return typeof value === "string";
+            case "number":
+                return typeof value === "number" && Number.isFinite(value);
+            case "integer":
+                return typeof value === "number" && Number.isInteger(value);
+            case "boolean":
+                return typeof value === "boolean";
+            case "null":
+                return value === null;
+            case "object":
+                return isObj(value);
+            case "array":
+                return Array.isArray(value);
+            default:
+                return false;
+        }
+    });
+}
 /**
- * Keep only what the schema declares, deep: `findings[].title` keeps `title` and nothing else. An
- * object with no declared properties is dropped (nothing in it was declared); scalars are kept.
- * Undefined means "drop".
+ * Keep only what the schema declares, deep, and only values whose shape matches it: `findings[].title`
+ * keeps `title` and nothing else, a string where an object is declared is dropped, as is a value of
+ * the wrong `type` or outside an `enum`. An object with no declared properties is dropped (nothing in
+ * it was declared). Undefined means "drop".
  */
 function pick(value, schema) {
     const sch = isObj(schema) ? schema : undefined;
+    if (sch) {
+        const types = declaredTypes(sch);
+        if (types && !typeMatches(value, types))
+            return undefined;
+        if (Array.isArray(sch.enum) && !isObj(value) && !Array.isArray(value) && !sch.enum.includes(value)) {
+            return undefined;
+        }
+    }
     if (Array.isArray(value)) {
         const items = sch && isObj(sch.items) ? sch.items : undefined;
         return value.map((v) => pick(v, items)).filter((v) => v !== undefined);
@@ -54,20 +97,24 @@ function pick(value, schema) {
     }
     return value;
 }
-/** Secrets in keys too (`redact` scrubs values and keeps keys). */
-function redactKeys(value, secrets) {
+/**
+ * Secrets in keys too (`redact` scrubs values and keeps keys). A key that redaction changes, or that
+ * already looks like a redacted name, becomes `[redacted-<first 16 hex of HMAC-SHA256(key)>]`, keyed
+ * with `macKey()`: injective (no two keys share a name, and no plain key can equal a generated one),
+ * stable (the same key gets the same name in every run, whatever else is present, so a diff lines
+ * them up) and not a guessing oracle for a low-entropy secret (a plain hash would be).
+ */
+function redactKeys(value, secrets, macKey) {
     if (Array.isArray(value))
-        return value.map((v) => redactKeys(v, secrets));
+        return value.map((v) => redactKeys(v, secrets, macKey));
     if (!isObj(value))
         return value;
-    const seen = new Map();
     return Object.fromEntries(Object.entries(value).map(([k, v]) => {
-        let name = redact(k, secrets).value;
-        const n = (seen.get(name) ?? 0) + 1;
-        seen.set(name, n);
-        if (n > 1)
-            name = `${name}#${n}`;
-        return [name, redactKeys(v, secrets)];
+        const scrubbed = redact(k, secrets).value;
+        const name = scrubbed !== k || k.startsWith("[redacted")
+            ? `[redacted-${crypto.createHmac("sha256", macKey()).update(k).digest("hex").slice(0, 16)}]`
+            : k;
+        return [name, redactKeys(v, secrets, macKey)];
     }));
 }
 /** [display value, digest tree]: strings over the cap are cut, and their full-text sha256 goes in the tree. */
@@ -97,6 +144,8 @@ function clipTree(value) {
  */
 export function buildRunAnswers(i) {
     const secrets = i.secrets ?? [];
+    let ephemeral;
+    const macKey = i.macKey ?? (() => (ephemeral ??= crypto.randomBytes(32)));
     const nodes = [];
     const digests = [];
     for (const [id, r] of i.results) {
@@ -109,12 +158,15 @@ export function buildRunAnswers(i) {
         if (isObj(props) && Object.keys(props).length > 0) {
             fields = pick(data, schema);
         }
-        else if (typeof data.summary === "string" && data.summary.trim() !== "") {
+        else if (typeof data.summary === "string" &&
+            data.summary.trim() !== "" &&
+            !(isObj(schema) && schema.additionalProperties === false)) {
+            // The free-form summary, unless the node's schema closes the object to its declared fields.
             fields = { summary: data.summary };
         }
         if (!isObj(fields) || Object.keys(fields).length === 0)
             continue;
-        const clean = redactKeys(redact(fields, secrets).value, secrets);
+        const clean = redactKeys(redact(fields, secrets).value, secrets, macKey);
         const [shown, digs] = clipTree(clean);
         nodes.push([id, shown]);
         if (digs !== undefined)
@@ -414,7 +466,10 @@ export function sinceLastRun(runId, workflowId, cwd = process.cwd()) {
 /** Save this run's answers, then compare with the previous run. Never throws. */
 export function recordRunAnswers(i, cwd = process.cwd()) {
     try {
-        if (!writeRunAnswers(buildRunAnswers(i), cwd))
+        // The key is per user and workspace and lives in the state dir; none usable means a process-only key.
+        let key;
+        const macKey = i.macKey ?? (() => (key ??= workspaceSecretKey(cwd, "answers") ?? crypto.randomBytes(32)));
+        if (!writeRunAnswers(buildRunAnswers({ ...i, macKey }), cwd))
             return null;
         return sinceLastRun(i.runId, i.workflow.id, cwd);
     }

package/dist/cli/run-history.js

@@ -19,6 +19,7 @@ import { openNoFollow } from "../safe-file.js";
 export const RUN_HISTORY_SCHEMA_VERSION = 1;
 export const RUN_HISTORY_DIR = path.join(".sweny", "runs");
 export const RUN_HISTORY_KEEP = 200;
+const RECORD_READ_MAX_BYTES = 1024 * 1024;
 // ── Hash + ids ──────────────────────────────────────────────────
 function canonicalize(value) {
     if (Array.isArray(value))
@@ -215,7 +216,12 @@ export function listRuns(cwd = process.cwd()) {
     const out = [];
     for (const f of files) {
         try {
-            const parsed = JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
+            // A link is not history: the target may be anywhere, and an agent can plant it.
+            const file = path.join(dir, f);
+            const st = fs.lstatSync(file);
+            if (!st.isFile() || st.size > RECORD_READ_MAX_BYTES)
+                continue;
+            const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
             if (isRecord(parsed) && RUN_ID_RE.test(parsed.run_id) && f === `${parsed.run_id}.json`)
                 out.push(parsed);
         }

package/dist/cli/runs.js

@@ -222,12 +222,14 @@ function formatAnswersSection(cmp, color, g) {
             out.push(p.muted(`        ${g.ellipsis} and ${list.length - MAX_ITEMS_SHOWN} more ${word}`));
         }
     };
+    // Node, field and nested field names are keys of agent-writable files: terminal text, not trusted.
+    const key = (s) => sanitizeTerminal(s, 64);
     const fields = (list) => {
         if (list.length === 0)
             return;
-        const w = Math.max(...list.map((f) => f.field.length));
+        const w = Math.max(...list.map((f) => key(f.field).length));
         for (const f of list.slice(0, MAX_FIELDS_SHOWN)) {
-            out.push(`            ${pad(f.field, w)}  ${valueChange(f.before, f.after, g)}`);
+            out.push(`            ${pad(key(f.field), w)}  ${valueChange(f.before, f.after, g)}`);
         }
         if (list.length > MAX_FIELDS_SHOWN)
             out.push(p.muted(`            ${g.ellipsis} and ${list.length - MAX_FIELDS_SHOWN} more fields`));
@@ -236,14 +238,14 @@ function formatAnswersSection(cmp, color, g) {
     for (const node of nodes) {
         const changed = cmp.entries.filter((e) => e.node === node && isChangedEntry(e));
         if (changed.length === 0) {
-            out.push(`    ${node}  ${p.muted("unchanged")}`);
+            out.push(`    ${key(node)}  ${p.muted("unchanged")}`);
             continue;
         }
-        out.push(`    ${node}`);
-        const w = Math.max(...changed.map((e) => e.field.length));
+        out.push(`    ${key(node)}`);
+        const w = Math.max(...changed.map((e) => key(e.field).length));
         for (const e of changed) {
             if (e.kind === "collection") {
-                out.push(`      ${pad(e.field, w)}  ${p.muted(countsHead(e, g))}`);
+                out.push(`      ${pad(key(e.field), w)}  ${p.muted(countsHead(e, g))}`);
                 items("+", p.warning, e.added, "added");
                 items("-", p.success, e.resolved, "resolved");
                 for (const c of e.changed.slice(0, MAX_ITEMS_SHOWN)) {
@@ -255,18 +257,18 @@ function formatAnswersSection(cmp, color, g) {
                 }
             }
             else if (e.status === "added") {
-                out.push(`      ${pad(e.field, w)}  ${p.warning("added")} ${showValue(e.after, g)}`);
+                out.push(`      ${pad(key(e.field), w)}  ${p.warning("added")} ${showValue(e.after, g)}`);
             }
             else if (e.status === "resolved") {
-                out.push(`      ${pad(e.field, w)}  ${p.success("resolved")} ${p.muted(`(was ${showValue(e.before, g)})`)}`);
+                out.push(`      ${pad(key(e.field), w)}  ${p.success("resolved")} ${p.muted(`(was ${showValue(e.before, g)})`)}`);
             }
             else {
-                out.push(`      ${pad(e.field, w)}  ${valueChange(e.before, e.after, g)}`);
+                out.push(`      ${pad(key(e.field), w)}  ${valueChange(e.before, e.after, g)}`);
             }
         }
     }
     for (const n of cmp.not_compared) {
-        out.push(`    ${n.node}  ${p.muted(`not compared (answer in ${n.only_in} only)`)}`);
+        out.push(`    ${key(n.node)}  ${p.muted(`not compared (answer in ${n.only_in} only)`)}`);
     }
     if (nodes.length === 0 && cmp.not_compared.length === 0)
         out.push(p.muted("    no declared outputs to compare"));

package/dist/harness/tool-bridge/protocol.d.ts

@@ -16,7 +16,7 @@
  * same `isError` status.
  */
 import { z } from "zod";
-import type { JSONSchema, Tool, ToolContext } from "../../types.js";
+import { type JSONSchema, type Tool, type ToolContext } from "../../types.js";
 export declare const BRIDGE_PROTOCOL_VERSION = 1;
 /** Frames longer than this are refused and the connection is dropped. */
 export declare const MAX_FRAME_BYTES: number;
@@ -73,7 +73,11 @@ export declare function createFrameReader(onFrame: (value: unknown) => void, onO
 export declare function tokenMatches(expected: string, given: unknown): boolean;
 /** Structural check of an incoming request frame (token checked separately). */
 export declare function parseRequest(value: unknown): BridgeRequest | undefined;
-/** A handler's return value as MCP content. Strings pass through; anything else is JSON. */
+/**
+ * A handler's return value as MCP content. Strings pass through; anything else
+ * is JSON. A {@link ToolRefusal} is a tool error (#544): the agent and the
+ * tool-call status (and so evals) see that the write did not happen.
+ */
 export declare function toolOutputToMcpResult(output: unknown): McpCallToolResult;
 /** A handler's thrown error as an MCP error result. */
 export declare function toolErrorToMcpResult(err: unknown): McpCallToolResult;

package/dist/harness/tool-bridge/protocol.js

@@ -17,6 +17,7 @@
  */
 import { timingSafeEqual } from "node:crypto";
 import { z } from "zod";
+import { isToolRefusal } from "../../types.js";
 export const BRIDGE_PROTOCOL_VERSION = 1;
 /** Frames longer than this are refused and the connection is dropped. */
 export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
@@ -86,8 +87,15 @@ export function parseRequest(value) {
     return value;
 }
 // ─── Tool result shape (shared with the in-process Claude path) ─────
-/** A handler's return value as MCP content. Strings pass through; anything else is JSON. */
+/**
+ * A handler's return value as MCP content. Strings pass through; anything else
+ * is JSON. A {@link ToolRefusal} is a tool error (#544): the agent and the
+ * tool-call status (and so evals) see that the write did not happen.
+ */
 export function toolOutputToMcpResult(output) {
+    if (isToolRefusal(output)) {
+        return { content: [{ type: "text", text: `Refused: ${output.reason}\n${JSON.stringify(output)}` }], isError: true };
+    }
     return {
         content: [{ type: "text", text: typeof output === "string" ? output : JSON.stringify(output) }],
     };

package/dist/journal.d.ts

@@ -47,6 +47,8 @@
  *                    write intents, written before the write stage runs
  *   output:intent    a write is about to be applied (idempotency key + tool)
  *   output:applied   the write returned (key + the ids it produced)
+ *   output:refused   the write's handler returned a refusal (#544): key, its
+ *                    fixed-wording reason and any ids it names; never applied
  *   node:end         final result of the visit and the write-stage counters
  *   route            the edge taken after the visit (null = the run ended), and the rung that chose it
  *   usage            spend of one agent attempt (cumulative; one per model turn that raised it, written
@@ -84,6 +86,15 @@
  * key with a receipt is not re-applied, and a key with an intent but no receipt
  * (the process died between the API call and the receipt) is looked up on the
  * provider by a marker embedded in the body before anything is re-sent.
+ *
+ * A handler that returns a refusal (`ToolRefusal`) gets `output:refused`
+ * instead of `output:applied`. On resume that refusal is replayed as is: the
+ * handler is not called and the provider is not searched (a marked write the
+ * refusal named would otherwise be taken for an applied one). The one
+ * exception is a refusal marked `transient` that names nothing it produced:
+ * nothing was written, so it goes through the unconfirmed-intent path above
+ * (provider lookup, then a first send). `--allow-repeat-writes` does not
+ * override a refusal: its outcome is known, not unconfirmed.
  */
 import type { Logger, NodeResult, NodeUsage, RouteRung, Skill, Workflow } from "./types.js";
 import type { SafeOutputIntent, WriteStageState } from "./safe-outputs.js";
@@ -143,6 +154,14 @@ export declare class JournalLocationError extends Error {
  * it points. Throws {@link JournalLocationError}.
  */
 export declare function assertStateOutsideWorkspace(dir: string, cwd: string): void;
+/**
+ * A 32-byte random key private to this user and workspace, for MACs that must stay the same from run to
+ * run (a run's journal key is per run, so it cannot serve). Stored hex, mode 0600, at
+ * `<state dir>/keys/<workspace-hash>.<purpose>.key`, read and created without following a link. Null
+ * when the state dir cannot be trusted (inside the workspace, where an agent can read it) or used;
+ * callers then fall back to a key that lives only in the process. Never written anywhere an agent reads.
+ */
+export declare function workspaceSecretKey(cwd: string, purpose: string, env?: Record<string, string | undefined>): Buffer | null;
 /** Thrown when a journal's key is missing or unreadable: its records cannot be checked. */
 export declare class JournalKeyError extends Error {
     constructor(file: string, why: string);
@@ -335,6 +354,8 @@ export interface PlannedVisit {
     rung?: RouteRung;
     /** Writes the checkpointed write stage already applied (receipts in the journal). */
     applied: number;
+    /** Writes whose handler refused (#544): the refusal is replayed, not re-sent. */
+    refused: number;
     /** Writes with an intent but no receipt: checked on the provider before anything is re-sent. */
     unconfirmed: number;
 }
@@ -356,6 +377,8 @@ export interface ResumePlan {
     ends: Map<string, EndRecord>;
     intents: Map<string, OutputRecord>;
     receipts: Map<string, OutputRecord>;
+    /** Writes whose handler refused (`output:refused`, #544): replayed on resume, never taken for applied. */
+    refusals: Map<string, OutputRecord>;
     /** Spend every earlier attempt journaled: the run budget starts here on resume. */
     priorSpend: Spend;
     /**

package/dist/journal.js

@@ -47,6 +47,8 @@
  *                    write intents, written before the write stage runs
  *   output:intent    a write is about to be applied (idempotency key + tool)
  *   output:applied   the write returned (key + the ids it produced)
+ *   output:refused   the write's handler returned a refusal (#544): key, its
+ *                    fixed-wording reason and any ids it names; never applied
  *   node:end         final result of the visit and the write-stage counters
  *   route            the edge taken after the visit (null = the run ended), and the rung that chose it
  *   usage            spend of one agent attempt (cumulative; one per model turn that raised it, written
@@ -84,11 +86,21 @@
  * key with a receipt is not re-applied, and a key with an intent but no receipt
  * (the process died between the API call and the receipt) is looked up on the
  * provider by a marker embedded in the body before anything is re-sent.
+ *
+ * A handler that returns a refusal (`ToolRefusal`) gets `output:refused`
+ * instead of `output:applied`. On resume that refusal is replayed as is: the
+ * handler is not called and the provider is not searched (a marked write the
+ * refusal named would otherwise be taken for an applied one). The one
+ * exception is a refusal marked `transient` that names nothing it produced:
+ * nothing was written, so it goes through the unconfirmed-intent path above
+ * (provider lookup, then a first send). `--allow-repeat-writes` does not
+ * override a refusal: its outcome is known, not unconfirmed.
  */
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isToolRefusal } from "./types.js";
 import { resolveNodePermissions } from "./node-policy.js";
 import { CURRENT_SPEC_VERSION } from "./migrations.js";
 import { spendOf } from "./budget.js";
@@ -301,6 +313,64 @@ export function assertStateOutsideWorkspace(dir, cwd) {
         throw new JournalLocationError(real, ws);
     }
 }
+/** True when `dir` (which may not exist yet) would resolve inside `cwd`: its nearest existing ancestor's real path decides. */
+function resolvesInside(dir, cwd) {
+    const ws = realOr(cwd);
+    let existing = path.resolve(dir);
+    const rest = [];
+    while (!fs.existsSync(existing) && path.dirname(existing) !== existing) {
+        rest.unshift(path.basename(existing));
+        existing = path.dirname(existing);
+    }
+    const real = path.join(realOr(existing), ...rest);
+    return real === ws || real.startsWith(ws.endsWith(path.sep) ? ws : ws + path.sep);
+}
+/**
+ * A 32-byte random key private to this user and workspace, for MACs that must stay the same from run to
+ * run (a run's journal key is per run, so it cannot serve). Stored hex, mode 0600, at
+ * `<state dir>/keys/<workspace-hash>.<purpose>.key`, read and created without following a link. Null
+ * when the state dir cannot be trusted (inside the workspace, where an agent can read it) or used;
+ * callers then fall back to a key that lives only in the process. Never written anywhere an agent reads.
+ */
+export function workspaceSecretKey(cwd, purpose, env = process.env) {
+    try {
+        const dir = path.join(swenyStateDir(env), "keys");
+        if (resolvesInside(dir, cwd))
+            return null;
+        makePrivateDir(dir);
+        if (resolvesInside(dir, cwd))
+            return null;
+        const file = path.join(dir, `${workspaceScope(cwd)}.${purpose.replace(/[^A-Za-z0-9_-]/g, "_")}.key`);
+        const read = () => {
+            const text = readNoFollow(file).toString("utf8").trim();
+            if (!/^[0-9a-f]{64}$/.test(text))
+                return null;
+            if (process.platform !== "win32" && (fs.lstatSync(file).mode & 0o077) !== 0)
+                return null;
+            return Buffer.from(text, "hex");
+        };
+        try {
+            return read();
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                return null;
+        }
+        const key = crypto.randomBytes(32);
+        try {
+            writeNew(file, key.toString("hex") + "\n");
+            return key;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                return null;
+            return read(); // another run created it first
+        }
+    }
+    catch {
+        return null;
+    }
+}
 /** Thrown when a journal's key is missing or unreadable: its records cannot be checked. */
 export class JournalKeyError extends Error {
     constructor(file, why) {
@@ -840,6 +910,7 @@ const RECORD_TYPES = new Set([
     "node:checkpoint",
     "output:intent",
     "output:applied",
+    "output:refused",
     "node:end",
     "route",
     "usage",
@@ -937,6 +1008,7 @@ export function checkRecordSequence(records) {
             }
             case "output:intent":
             case "output:applied":
+            case "output:refused":
                 inVisit(r);
                 if (!checkpointed.has(visitKey(r.node, r.iteration))) {
                     bad(r, "records a write before the visit's checkpoint");
@@ -1057,6 +1129,7 @@ export function buildResumePlan(records) {
     const byKey = new Map();
     const intents = new Map();
     const receipts = new Map();
+    const refusals = new Map();
     let attempts = 1;
     let lastStatus;
     let deciderCounters;
@@ -1113,6 +1186,9 @@ export function buildResumePlan(records) {
             case "output:applied":
                 receipts.set(r.key, r);
                 break;
+            case "output:refused":
+                refusals.set(r.key, r);
+                break;
             case "run:end":
                 lastStatus = r.status;
                 break;
@@ -1129,7 +1205,8 @@ export function buildResumePlan(records) {
         const complete = !!v.end && !(isLast && v.end.result.status === "failed" && typeof v.next !== "string");
         const keys = (rec) => [...rec.values()].filter((o) => o.node === v.node && o.iteration === v.iteration).map((o) => o.key);
         const applied = keys(receipts).length;
-        const unconfirmed = keys(intents).filter((k) => !receipts.has(k)).length;
+        const refused = keys(refusals).filter((k) => !receipts.has(k)).length;
+        const unconfirmed = keys(intents).filter((k) => !receipts.has(k) && !refusals.has(k)).length;
         if (complete && !resumed) {
             visits.push({
                 node: v.node,
@@ -1139,6 +1216,7 @@ export function buildResumePlan(records) {
                 next: v.next,
                 ...(v.rung ? { rung: v.rung } : {}),
                 applied,
+                refused,
                 unconfirmed,
             });
             writeState = v.end.write_state;
@@ -1150,6 +1228,7 @@ export function buildResumePlan(records) {
             iteration: v.iteration,
             action: v.checkpoint ? "write-stage" : "rerun",
             applied,
+            refused,
             unconfirmed,
         });
         break;
@@ -1180,6 +1259,7 @@ export function buildResumePlan(records) {
         ends,
         intents,
         receipts,
+        refusals,
         priorSpend: journaledSpend(records),
         unsandboxed: [...new Set(records.filter((r) => r.type === "agent:unsandboxed").map((r) => String(r.node)))],
         ...(start.decider
@@ -1336,6 +1416,14 @@ function slimOutput(o, depth = 0) {
     if (!o || typeof o !== "object" || Array.isArray(o) || depth > 3)
         return null;
     const out = {};
+    // A refusal keeps what it is and its fixed-wording reason (#544); never `detail`.
+    if (depth === 0 && o.refused === true) {
+        out.refused = true;
+        if (isToolRefusal(o))
+            out.reason = o.reason;
+        if (o.transient === true)
+            out.transient = true;
+    }
     for (const [k, v] of Object.entries(o)) {
         if (["number", "identifier", "id", "html_url", "url", "success", "reused"].includes(k)) {
             if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
@@ -1805,6 +1893,12 @@ export class RunJournal {
                     this.logger.info(`  run journal: ${tool.name} already applied before the crash; not re-sent`, { node });
                     return receipt.output ?? null;
                 }
+                const refusal = plan?.refusals.get(key);
+                if (refusal && !retriesRefusal(refusal.output)) {
+                    this.logger.info(`  run journal: ${tool.name} was refused in an earlier attempt; not re-sent`, { node });
+                    const prior = refusal.output && typeof refusal.output === "object" ? refusal.output : {};
+                    return { reason: "the tool refused the write", ...prior, refused: true };
+                }
                 const replayingStage = !!plan?.checkpoints.has(visitKey(node, iteration));
                 const pending = plan?.intents.has(key) === true;
                 if (pending || replayingStage) {
@@ -1826,12 +1920,30 @@ export class RunJournal {
                 // A write the journal cannot record is never sent: append throws first.
                 this.append("output:intent", { node, iteration, key, tool: tool.name });
                 const output = await tool.handler(withMarker(tool.name, args, key), ctx);
-                this.append("output:applied", { node, iteration, key, tool: tool.name, output: slimOutput(output) });
+                const refused = !!output && typeof output === "object" && output.refused === true;
+                this.append(refused ? "output:refused" : "output:applied", {
+                    node,
+                    iteration,
+                    key,
+                    tool: tool.name,
+                    output: slimOutput(output),
+                });
                 return output;
             },
         };
     }
 }
+/**
+ * Whether a journaled refusal is tried again on resume (#544): only a
+ * transient one that names nothing it produced. Anything else stands.
+ */
+function retriesRefusal(output) {
+    if (!output || typeof output !== "object")
+        return false;
+    const o = output;
+    // Anything besides the refusal itself is something the write produced.
+    return o.transient === true && Object.keys(o).every((k) => k === "refused" || k === "reason" || k === "transient");
+}
 /** What a node result needs to continue a run. Tool call inputs and outputs are dropped. */
 function journalResult(r) {
     return {

package/dist/safe-outputs.d.ts

@@ -114,7 +114,7 @@ export interface ApplySafeOutputsOptions {
 }
 export interface ApplySafeOutputsResult {
     receipts: SafeOutputReceipt[];
-    /** Set when an apply call failed; the node fails with it. */
+    /** Set when an apply call failed or its handler refused (a `ToolRefusal`); the node fails with it. */
     error?: string;
 }
 /** Check, then apply (or stage) one node's intents. See the module comment for the order of checks. */

package/dist/safe-outputs.js

@@ -15,7 +15,7 @@
  */
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { SAFE_OUTPUT_APPLIERS } from "./types.js";
+import { SAFE_OUTPUT_APPLIERS, isToolRefusal } from "./types.js";
 /** Name of the intent-recording tool a node with `outputs` receives. */
 export const EMIT_OUTPUT_TOOL = "emit_output";
 /** Longest title the write stage accepts (after the prefix). */
@@ -574,7 +574,22 @@ export async function applySafeOutputs(o) {
             });
             const ref = refOf(output);
             const url = urlOf(output);
-            receipts[index] = { ...receipts[index], ...(ref !== undefined ? { ref } : {}), ...(url ? { url } : {}) };
+            const produced = { ...(ref !== undefined ? { ref } : {}), ...(url ? { url } : {}) };
+            const refused = !!output && typeof output === "object" && output.refused === true;
+            if (refused) {
+                // #544: the handler declined the write, or could not vouch for it. The
+                // receipt says refused with the handler's fixed-wording reason (and
+                // names anything it did create); the node fails and the rest are
+                // skipped, the same as a failed apply. A refusal without a usable
+                // reason still counts as one.
+                const reason = isToolRefusal(output) ? output.reason.slice(0, 200) : "the tool refused the write";
+                receipts[index] = { ...receipts[index], ...produced, status: "refused", reason };
+                for (const rest of accepted.slice(n + 1)) {
+                    receipts[rest.index] = { ...receipts[rest.index], status: "skipped", reason: "an earlier write was refused" };
+                }
+                return { receipts, error: `safe output ${write.type} via ${write.via} was refused: ${reason}` };
+            }
+            receipts[index] = { ...receipts[index], ...produced };
             o.logger.info(`  safe output: ${write.type} via ${write.via} applied${ref !== undefined ? ` (${ref})` : ""}`, {
                 node: o.nodeId,
             });

package/dist/skills/git-push.d.ts

@@ -110,6 +110,12 @@ export interface PushHeadResult {
     attempted: boolean;
     /** Why nothing was pushed, or why the push failed. Never carries the token. */
     reason?: string;
+    /**
+     * The local commit the push tried to publish. Set when the push ran and
+     * failed: `github_create_pr` then opens the PR only if the remote head is
+     * this commit (#544).
+     */
+    sha?: string;
 }
 /** `owner/repo` from a GitHub remote URL (https, ssh or scp form), lowercased, or undefined. */
 export declare function repoFromRemote(url: string): {

package/dist/skills/git-push.js

@@ -459,7 +459,7 @@ export async function pushHeadBranch(opts) {
         ], pushEnv);
         if (r.code !== 0) {
             const why = (r.stderr || r.stdout).trim().split("\n").at(-1) ?? "";
-            return { pushed: false, attempted: true, reason: `git push failed: ${redact(why, token)}` };
+            return { pushed: false, attempted: true, reason: `git push failed: ${redact(why, token)}`, sha };
         }
         return { pushed: true, attempted: true };
     }

package/dist/skills/github.d.ts

@@ -19,12 +19,13 @@ export declare function githubApiBase(apiUrl: string | undefined): string;
  * remotely is pushed with an empty lease (it must still not exist). One that
  * exists is pushed only when it is unprotected and already has an open PR from
  * this repo into `base`, leased on the sha the API returned. Any API failure
- * means no push.
+ * means no push. A skip carries the remote head sha when the API returned one.
  */
 export declare function headPushLease(repo: string, head: string, base: string, ctx: ToolContext): Promise<{
     remoteSha: string;
 } | {
     skip: string;
+    remoteSha?: string;
 }>;
 /**
  * Encode an LLM-chosen repo file path for safe interpolation into a

package/dist/skills/github.js

@@ -56,7 +56,7 @@ async function gh(path, ctx, init) {
  * remotely is pushed with an empty lease (it must still not exist). One that
  * exists is pushed only when it is unprotected and already has an open PR from
  * this repo into `base`, leased on the sha the API returned. Any API failure
- * means no push.
+ * means no push. A skip carries the remote head sha when the API returned one.
  */
 export async function headPushLease(repo, head, base, ctx) {
     const branch = head.replace(/^refs\/heads\//, "");
@@ -76,7 +76,7 @@ export async function headPushLease(repo, head, base, ctx) {
         return { skip: `cannot check head ${branch} on ${repo}: no branch sha in the API answer` };
     }
     if (info.protected !== false)
-        return { skip: `head ${branch} exists on ${repo} and is protected` };
+        return { skip: `head ${branch} exists on ${repo} and is protected`, remoteSha: sha };
     const owner = repo.split("/")[0];
     let open;
     try {
@@ -85,13 +85,45 @@ export async function headPushLease(repo, head, base, ctx) {
     catch (err) {
         return {
             skip: `cannot check open PRs for ${branch} on ${repo}: ${err instanceof Error ? err.message : String(err)}`,
+            remoteSha: sha,
         };
     }
     if (!Array.isArray(open) || open.length === 0) {
-        return { skip: `head ${branch} already exists on ${repo} with no open PR into ${target}` };
+        return { skip: `head ${branch} already exists on ${repo} with no open PR into ${target}`, remoteSha: sha };
     }
     return { remoteSha: sha };
 }
+const SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+// Fixed-wording refusal reasons for `github_create_pr` (#544). Receipts and PR
+// comments carry these; shas and upstream errors go in the result's `detail`.
+const REFUSE_NO_LOCAL = "the head push failed and the pusher did not report the local commit";
+const REFUSE_UNREADABLE = "the head push failed and the remote head could not be read";
+const REFUSE_MISMATCH = "the head push failed and the remote head is not the commit this run produced";
+const REFUSE_PR_MISMATCH = "the PR was opened but its head is not the commit this run produced";
+const REFUSE_PR_UNVERIFIED = "the PR was opened but its head commit could not be verified";
+/**
+ * The sha the remote `head` branch points at, read through the API (#544), or
+ * an error. A missing branch is `{ sha: null }`; anything unreadable is an error,
+ * so the caller fails closed.
+ */
+async function remoteHeadSha(repo, head, ctx) {
+    const branch = head.replace(/^refs\/heads\//, "");
+    const seg = branch.split("/").map(encodeURIComponent).join("/");
+    let ref;
+    try {
+        ref = (await gh(`/repos/${repo}/git/ref/heads/${seg}`, ctx));
+    }
+    catch (err) {
+        if (err instanceof GitHubApiError && err.status === 404)
+            return { sha: null };
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    const sha = ref?.object?.sha;
+    if (ref?.ref !== `refs/heads/${branch}` || typeof sha !== "string" || !SHA.test(sha)) {
+        return { error: "no matching ref in the API answer" };
+    }
+    return { sha };
+}
 function isAlreadyExistsError(err) {
     if (!(err instanceof GitHubApiError) || err.status !== 422)
         return false;
@@ -280,6 +312,10 @@ export const github = {
             handler: async (input, ctx) => {
                 let pr;
                 let reused = false;
+                // The remote head this run saw, for the result (#544).
+                let observedHead;
+                // Set after sweny's own push failed: the PR's head must be this commit (#544).
+                let mustHead;
                 // #473: push the head branch from sweny with this skill's token, so the
                 // recommended `persist-credentials: false` checkout still ships the
                 // branch and the agent never holds a write token. Skipped unless the
@@ -307,12 +343,49 @@ export const github = {
                             remoteSha: lease.remoteSha,
                             token: ctx.config.GITHUB_TOKEN,
                         });
+                    if (lease.remoteSha)
+                        observedHead = lease.remoteSha;
                     if ("skip" in lease)
                         ctx.logger?.warn?.(`  github_create_pr: not pushing: ${lease.skip}`);
                     else if (push.pushed)
                         ctx.logger?.info?.(`  github_create_pr: pushed ${input.head} to ${input.repo}`);
-                    else if (push.attempted)
-                        ctx.logger?.warn?.(`  github_create_pr: ${push.reason}; requesting the PR anyway`);
+                    else if (push.attempted) {
+                        // #544: a push sweny ran and that failed. The PR would publish
+                        // whatever the remote branch holds, so open it only when that is
+                        // the commit this run would have pushed. Anything else, or a
+                        // remote head that cannot be read, refuses.
+                        const local = typeof push.sha === "string" && SHA.test(push.sha) ? push.sha : null;
+                        const remote = local ? await remoteHeadSha(input.repo, input.head, ctx) : undefined;
+                        const remoteSha = remote && "sha" in remote ? remote.sha : null;
+                        if (!local || !remoteSha || remoteSha !== local) {
+                            const [reason, why] = !local
+                                ? [REFUSE_NO_LOCAL, "the pusher did not report the local commit"]
+                                : remote && "error" in remote
+                                    ? [REFUSE_UNREADABLE, `cannot read the remote head of ${input.head}: ${remote.error}`]
+                                    : remoteSha
+                                        ? [
+                                            REFUSE_MISMATCH,
+                                            `the remote head of ${input.head} is ${remoteSha}, not the local commit ${local}`,
+                                        ]
+                                        : [REFUSE_MISMATCH, `${input.head} does not exist on ${input.repo}; the local commit is ${local}`];
+                            const detail = `sweny's push failed (${push.reason}) and ${why}`;
+                            ctx.logger?.warn?.(`  github_create_pr: refusing to open the PR: ${detail}`);
+                            const refusal = {
+                                refused: true,
+                                reason,
+                                detail,
+                                // A ref read that failed may succeed later; nothing was written.
+                                ...(reason === REFUSE_UNREADABLE ? { transient: true } : {}),
+                                head: input.head,
+                                local_sha: local,
+                                remote_sha: remoteSha,
+                            };
+                            return refusal;
+                        }
+                        observedHead = remoteSha;
+                        mustHead = local;
+                        ctx.logger?.warn?.(`  github_create_pr: ${push.reason}; the remote head is already the local commit ${local}, requesting the PR`);
+                    }
                     else
                         ctx.logger?.debug?.(`  github_create_pr: no sweny-side push (${push.reason})`);
                 }
@@ -347,6 +420,29 @@ export const github = {
                     pr = existing;
                     reused = true;
                 }
+                // #544: the remote could move between the ref read and the request. The
+                // PR exists now; it is not closed (that would be another write nobody
+                // asked for), but the result refuses to vouch for it.
+                const prHead = pr.head?.sha;
+                const prHeadSha = typeof prHead === "string" && SHA.test(prHead) ? prHead : null;
+                if (mustHead && prHeadSha !== mustHead) {
+                    const detail = prHeadSha
+                        ? `the PR's head is ${prHeadSha}, not the local commit ${mustHead}`
+                        : `GitHub did not report the PR's head commit; the local commit is ${mustHead}`;
+                    ctx.logger?.warn?.(`  github_create_pr: ${pr.html_url ?? `#${pr.number}`} is not verified: ${detail}`);
+                    const refusal = {
+                        refused: true,
+                        reason: prHeadSha ? REFUSE_PR_MISMATCH : REFUSE_PR_UNVERIFIED,
+                        detail,
+                        ...(pr.number !== undefined ? { number: pr.number } : {}),
+                        ...(pr.html_url ? { html_url: pr.html_url } : {}),
+                        ...(reused ? { reused: true } : {}),
+                        head: input.head,
+                        local_sha: mustHead,
+                        remote_sha: prHeadSha,
+                    };
+                    return refusal;
+                }
                 try {
                     if (pr.number && !reused) {
                         await gh(`/repos/${input.repo}/issues/${pr.number}/labels`, ctx, {
@@ -364,7 +460,10 @@ export const github = {
                     const msg = err instanceof Error ? err.message : String(err);
                     ctx.logger?.warn?.(`  github_create_pr: label POST failed for ${pr.html_url ?? `#${pr.number}`} — ${msg}`);
                 }
-                return reused ? { ...pr, reused: true } : pr;
+                // The head the PR was opened from: GitHub's answer, else the remote head this run read.
+                const headSha = prHeadSha ?? observedHead;
+                const out = headSha ? { ...pr, head_sha: headSha } : pr;
+                return reused ? { ...out, reused: true } : out;
             },
         },
         {

package/dist/types.d.ts

@@ -48,6 +48,11 @@ export type BranchPusher = (opts: {
     pushed: boolean;
     attempted: boolean;
     reason?: string;
+    /**
+     * The local commit the push tried to publish. Set when a push was attempted
+     * and failed, so the caller can check what the remote head holds (#544).
+     */
+    sha?: string;
 }>;
 /**
  * Side-effect class of a tool. `"read"` only reads. `"write"` can change
@@ -68,6 +73,32 @@ export interface Tool {
     access?: ToolAccess;
     handler: (input: any, ctx: ToolContext) => Promise<unknown>;
 }
+/**
+ * A write handler's structured refusal: it declined the write, or could not
+ * vouch for what it wrote, and says why. Returned, not thrown, so the caller
+ * keeps the details. `refused: true` is the same flag a refused node result
+ * carries (`data: { error, refused: true }`). The write stage records it as
+ * refused, never applied (#544).
+ *
+ * `reason` is fixed wording chosen by the handler, never model, agent or
+ * remote text: receipts and PR comments carry it. Specifics (shas, branch
+ * names, upstream errors) go in `detail` and other fields, which only the
+ * tool result carries. A refusal may still name what exists (`number`,
+ * `html_url`) when the write happened but could not be verified.
+ */
+export interface ToolRefusal {
+    refused: true;
+    reason: string;
+    detail?: string;
+    /**
+     * The refusal may not hold on a later try (an upstream read failed) and
+     * nothing was written. Only such a refusal is tried again when a run is
+     * resumed; any other refusal is final for the run.
+     */
+    transient?: boolean;
+}
+/** Whether a tool handler's output is a {@link ToolRefusal}. */
+export declare function isToolRefusal(output: unknown): output is ToolRefusal;
 /** Config field declaration — skills say what they need */
 export interface ConfigField {
     description: string;

package/dist/types.js

@@ -4,6 +4,13 @@ export { WORKFLOW_INPUT_TYPES } from "./inputs.js";
  * something outside the run: create, update, delete, post, send, invoke.
  */
 export const TOOL_ACCESS = ["read", "write"];
+/** Whether a tool handler's output is a {@link ToolRefusal}. */
+export function isToolRefusal(output) {
+    if (!output || typeof output !== "object" || Array.isArray(output))
+        return false;
+    const o = output;
+    return o.refused === true && typeof o.reason === "string" && o.reason.length > 0;
+}
 /**
  * Skill categories: used for per-node validation and grouping.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.189",
+  "version": "0.1.191",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"