@sweny-ai/core 0.1.209 → 0.1.211

package/dist/harness/claude-code.d.ts

@@ -34,11 +34,12 @@ export declare const CLASSIFICATION_DISALLOWED_TOOLS: readonly ["Bash", "Write",
 /**
  * Built-in tools disallowed for a node run with `readOnly: true` (dry run,
  * #380): everything that can edit the workspace, shell out (and so reach
- * `gh`, `curl`, `git push`), spawn a subagent that could, or fetch an
- * arbitrary URL (a GET can still trigger a webhook or exfiltrate data).
- * Read, Grep, Glob and WebSearch stay available for analysis.
+ * `gh`, `curl`, `git push`), spawn a subagent that could, fetch an arbitrary
+ * URL (a GET can still trigger a webhook or exfiltrate data) or search the web
+ * (a query is an egress channel that can carry repo data out). Read, Grep and
+ * Glob stay available for analysis.
  */
-export declare const READ_ONLY_DISALLOWED_TOOLS: readonly ["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit", "Task", "Agent", "WebFetch"];
+export declare const READ_ONLY_DISALLOWED_TOOLS: readonly ["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit", "Task", "Agent", "WebFetch", "WebSearch"];
 /**
  * Claude Code built-in tool names per portable tool class. A node's
  * `tools.deny` classes compile to these names on `disallowedTools`.
@@ -71,6 +72,40 @@ export declare function claudeReadDenyRule(absPath: string): string;
 export declare function claudeStateDirDenyRules(root?: string): string[];
 /** Native `disallowedTools` for a policy: legacy names, compiled classes, and the read-only set. */
 export declare function compileClaudeCodeDeny(policy: NodePolicy, legacy?: readonly string[]): string[];
+/**
+ * The only Claude Code built-in tools a node may get, by policy. Every node
+ * reads and searches the checkout, and a read-only node gets nothing else: no
+ * web search or fetch, since either can carry repo data out. A write node adds
+ * the shell, file-edit and web built-ins (its `tools.deny` classes and
+ * `disallowed_tools` names then leave the list). No node gets the subagent
+ * tools (Task, Agent) by default: nothing shows a subagent is held to its
+ * parent's `tools`, so the default must not depend on it.
+ *
+ * Passed as the SDK's `tools` option, which "Specif[ies] the base set of
+ * available built-in tools" (sdk.d.ts); `allowedTools` only auto-approves
+ * ("To restrict which tools are available, use the `tools` option instead").
+ * Anything not named here never reaches a node: agent-to-agent messaging
+ * (SendMessage, ListAgents), scheduling (Cron*, ScheduleWakeup), remote
+ * triggers, notifications, worktrees, design sync, Skill, Workflow and
+ * ToolSearch (added back only while a server defers its tools, see
+ * {@link runQuery}). Dogfood run 42890468912 listed 23 tools for a read-only
+ * node that needed two.
+ */
+export declare const CLAUDE_READ_ONLY_BUILTIN_TOOLS: readonly ["Read", "Grep", "Glob"];
+export declare const CLAUDE_WRITE_BUILTIN_TOOLS: readonly ["Read", "Grep", "Glob", ...string[]];
+/**
+ * The built-in allow-list for one node: the policy's list minus every name the
+ * compiled deny list removes. Path-scoped rules (`Read(//dir/**)`) narrow a
+ * tool, they do not remove it, so they are not matched here.
+ */
+export declare function claudeCodeBuiltinTools(policy: {
+    readOnly: boolean;
+}, deny?: readonly string[]): string[];
+/**
+ * Env vars the harness itself sets on the agent (not passed through from the
+ * parent): `ENABLE_TOOL_SEARCH`, see {@link ClaudeCodeHarness} runQuery.
+ */
+export declare const CLAUDE_CODE_HARNESS_VARS: readonly ["ENABLE_TOOL_SEARCH"];
 /** How sweny resolves which credentials reach the Claude Code subprocess. */
 export type SwenyAuthMode = "auto" | "api-key" | "oauth";
 export interface ResolveAuthEnvOpts {

package/dist/harness/claude-code.js

@@ -68,9 +68,10 @@ export const CLASSIFICATION_DISALLOWED_TOOLS = [
 /**
  * Built-in tools disallowed for a node run with `readOnly: true` (dry run,
  * #380): everything that can edit the workspace, shell out (and so reach
- * `gh`, `curl`, `git push`), spawn a subagent that could, or fetch an
- * arbitrary URL (a GET can still trigger a webhook or exfiltrate data).
- * Read, Grep, Glob and WebSearch stay available for analysis.
+ * `gh`, `curl`, `git push`), spawn a subagent that could, fetch an arbitrary
+ * URL (a GET can still trigger a webhook or exfiltrate data) or search the web
+ * (a query is an egress channel that can carry repo data out). Read, Grep and
+ * Glob stay available for analysis.
  */
 export const READ_ONLY_DISALLOWED_TOOLS = [
     "Bash",
@@ -81,6 +82,7 @@ export const READ_ONLY_DISALLOWED_TOOLS = [
     "Task",
     "Agent",
     "WebFetch",
+    "WebSearch",
 ];
 /**
  * Claude Code built-in tool names per portable tool class. A node's
@@ -146,6 +148,55 @@ export function compileClaudeCodeDeny(policy, legacy = []) {
         ]),
     ];
 }
+/**
+ * The only Claude Code built-in tools a node may get, by policy. Every node
+ * reads and searches the checkout, and a read-only node gets nothing else: no
+ * web search or fetch, since either can carry repo data out. A write node adds
+ * the shell, file-edit and web built-ins (its `tools.deny` classes and
+ * `disallowed_tools` names then leave the list). No node gets the subagent
+ * tools (Task, Agent) by default: nothing shows a subagent is held to its
+ * parent's `tools`, so the default must not depend on it.
+ *
+ * Passed as the SDK's `tools` option, which "Specif[ies] the base set of
+ * available built-in tools" (sdk.d.ts); `allowedTools` only auto-approves
+ * ("To restrict which tools are available, use the `tools` option instead").
+ * Anything not named here never reaches a node: agent-to-agent messaging
+ * (SendMessage, ListAgents), scheduling (Cron*, ScheduleWakeup), remote
+ * triggers, notifications, worktrees, design sync, Skill, Workflow and
+ * ToolSearch (added back only while a server defers its tools, see
+ * {@link runQuery}). Dogfood run 42890468912 listed 23 tools for a read-only
+ * node that needed two.
+ */
+export const CLAUDE_READ_ONLY_BUILTIN_TOOLS = ["Read", "Grep", "Glob"];
+export const CLAUDE_WRITE_BUILTIN_TOOLS = [
+    "Read",
+    "Grep",
+    "Glob",
+    ...CLAUDE_TOOLS_BY_CLASS.shell,
+    ...CLAUDE_TOOLS_BY_CLASS.write,
+    ...CLAUDE_TOOLS_BY_CLASS.edit,
+    ...CLAUDE_TOOLS_BY_CLASS.net,
+];
+/**
+ * The built-in allow-list for one node: the policy's list minus every name the
+ * compiled deny list removes. Path-scoped rules (`Read(//dir/**)`) narrow a
+ * tool, they do not remove it, so they are not matched here.
+ */
+export function claudeCodeBuiltinTools(policy, deny = []) {
+    const denied = new Set(deny);
+    const base = policy.readOnly ? CLAUDE_READ_ONLY_BUILTIN_TOOLS : CLAUDE_WRITE_BUILTIN_TOOLS;
+    return base.filter((t) => !denied.has(t));
+}
+/**
+ * Env vars the harness itself sets on the agent (not passed through from the
+ * parent): `ENABLE_TOOL_SEARCH`, see {@link ClaudeCodeHarness} runQuery.
+ */
+export const CLAUDE_CODE_HARNESS_VARS = ["ENABLE_TOOL_SEARCH"];
+/** CI: a truthy `CI` (not "", "0", "false", "no", "off"), or GitHub Actions itself. */
+function runningInCi(env = process.env) {
+    const ci = (env.CI ?? "").trim().toLowerCase();
+    return env.GITHUB_ACTIONS === "true" || !["", "0", "false", "no", "off"].includes(ci);
+}
 /**
  * Decide which auth credentials survive into the Claude Code subprocess env.
  *
@@ -562,6 +613,8 @@ export class ClaudeCodeHarness {
         // Fail closed: a stream that ends with no terminal `result` message
         // (subprocess died, stream truncated) is not a success.
         let sawResult = false;
+        // The tool names the agent was given (init message), for the executor's repair rule.
+        let agentTools;
         // Timeout / abort wiring (back-compat: only armed when requested).
         // A single AbortController drives both an optional caller signal and an
         // optional timeout timer. The SDK aborts the subprocess when this fires.
@@ -596,6 +649,20 @@ export class ClaudeCodeHarness {
             else if (sdkTools.length > 0) {
                 allMcpServers["sweny-core"] = mcpServer;
             }
+            // Deterministic tool loading: when every server loads its tools up front
+            // (sweny-core always does; a node's skill servers do unless they opt out),
+            // tool search has nothing to defer, so it is off and ToolSearch is not on
+            // the list. `ENABLE_TOOL_SEARCH=false` is the bundled CLI's switch (its
+            // own docs: "To turn it off ... set `ENABLE_TOOL_SEARCH` to `false`"; CLI
+            // 0.3.319 drops ToolSearch from the init tool list with it). A client-level
+            // server not marked alwaysLoad keeps tool search, and ToolSearch, so its
+            // deferred tools stay reachable.
+            const defers = Object.entries(allMcpServers).some(([name, cfg]) => name !== "sweny-core" && cfg?.alwaysLoad !== true);
+            if (!defers)
+                env.ENABLE_TOOL_SEARCH = "false";
+            const builtinTools = opts.nativeNone
+                ? []
+                : [...claudeCodeBuiltinTools({ readOnly: !!readOnly }, disallowedTools), ...(defers ? ["ToolSearch"] : [])];
             stream = query({
                 prompt,
                 options: {
@@ -622,10 +689,13 @@ export class ClaudeCodeHarness {
                     strictMcpConfig: true,
                     settingSources: [],
                     ...(disallowedTools && disallowedTools.length > 0 ? { disallowedTools } : {}),
-                    // permissions.native: none. `tools: []` removes every built-in tool whatever its
-                    // name; `settingSources: []` loads no user, project or local settings, CLAUDE.md or skills
-                    // (already the default above since #497; kept so the policy value states its whole contract).
-                    ...(opts.nativeNone ? { tools: [], settingSources: [] } : {}),
+                    // Least privilege: only the built-ins this node's policy names (see
+                    // CLAUDE_WRITE_BUILTIN_TOOLS). permissions.native: none passes `tools: []`,
+                    // which removes every built-in tool whatever its name.
+                    tools: builtinTools,
+                    // `settingSources: []` loads no user, project or local settings, CLAUDE.md or skills
+                    // (already the default above since #497; kept so native: none states its whole contract).
+                    ...(opts.nativeNone ? { settingSources: [] } : {}),
                     // CC-08: ask the SDK to produce validated structured output when the
                     // node declares an output schema. The SDK then returns the parsed
                     // value on `result.structured_output`, which we prefer over the
@@ -635,11 +705,27 @@ export class ClaudeCodeHarness {
             });
             for await (const message of stream) {
                 if (message.type === "system" && message.subtype === "init") {
-                    // What the agent was actually given: the tool list (--verbose) and,
-                    // loudly, a node tool server that did not come up.
+                    // What the agent was actually given: the tool names (never inputs)
+                    // and, loudly, a node tool or tool server that did not make it onto
+                    // the list. In CI the names go out as one warning-level line, the
+                    // level the default (non-verbose) run log shows, so a failed node is
+                    // diagnosable without a verbose rerun; locally they stay at info.
                     const init = message;
-                    if (Array.isArray(init.tools))
-                        this.logger.debug(`  agent tools: ${init.tools.join(", ")}`);
+                    if (Array.isArray(init.tools)) {
+                        agentTools = init.tools.filter((t) => typeof t === "string");
+                        const line = `  agent tools: ${init.tools.join(", ")}`;
+                        if (runningInCi())
+                            this.logger.warn(line);
+                        else
+                            this.logger.info(line);
+                        const listed = new Set(init.tools);
+                        const absent = allMcpServers["sweny-core"]
+                            ? tools.map((t) => t.name).filter((n) => !listed.has(`mcp__sweny-core__${n}`))
+                            : [];
+                        if (absent.length > 0) {
+                            this.logger.warn(`  node tools missing from the agent's tool list: ${absent.join(", ")}`);
+                        }
+                    }
                     const core = Array.isArray(init.mcp_servers)
                         ? init.mcp_servers.find((s) => s?.name === "sweny-core")
                         : undefined;
@@ -833,6 +919,7 @@ export class ClaudeCodeHarness {
             data: { summary: response, ...parsedData },
             toolCalls,
             ...(usage ? { usage } : {}),
+            ...(agentTools ? { agentTools } : {}),
         };
     }
     /**

package/dist/harness/types.d.ts

@@ -152,6 +152,14 @@ export interface HarnessRunRequest extends ClaudeRunRequest {
 export interface HarnessRunResult extends NodeResult {
     harness: HarnessInfo;
     degraded: string[];
+    /**
+     * Names of every tool the agent was given for this run, as the agent itself
+     * listed them (Claude Code: the init message; MCP tools as
+     * `mcp__<server>__<tool>`). The executor repairs a skipped required tool
+     * only when it is on this list. Absent when the harness does not report it,
+     * and then no such repair happens. Never journaled.
+     */
+    agentTools?: string[];
 }
 export interface HarnessCompleteRequest {
     prompt: string;

package/dist/journal.d.ts

@@ -123,7 +123,8 @@ export declare function canonicalHash(value: unknown): string;
 /**
  * Hash of the workflow a journal is bound to: the canonical workflow plus its
  * effective `spec_version` (#469), so a file that only changes spec version
- * (and therefore migrations) is a different workflow for resume.
+ * (and therefore migrations) is a different workflow for resume. Absent means
+ * 1, the version such a workflow runs as (#598), not the current one.
  */
 export declare function workflowHashOf(workflow: Workflow): string;
 /** Hash of what the nodes were told: every resolved instruction, rule and context Source. */

package/dist/journal.js

@@ -109,7 +109,7 @@ import os from "node:os";
 import path from "node:path";
 import { isRefusal, refusalReason } from "./types.js";
 import { resolveNodePermissions } from "./node-policy.js";
-import { CURRENT_SPEC_VERSION } from "./migrations.js";
+import { effectiveSpecVersion } from "./migrations.js";
 import { spendOf } from "./budget.js";
 /**
  * v3: each record's HMAC chains the run id and the previous record's HMAC.
@@ -152,10 +152,11 @@ export function canonicalHash(value) {
 /**
  * Hash of the workflow a journal is bound to: the canonical workflow plus its
  * effective `spec_version` (#469), so a file that only changes spec version
- * (and therefore migrations) is a different workflow for resume.
+ * (and therefore migrations) is a different workflow for resume. Absent means
+ * 1, the version such a workflow runs as (#598), not the current one.
  */
 export function workflowHashOf(workflow) {
-    return canonicalHash({ ...workflow, spec_version: workflow.spec_version ?? String(CURRENT_SPEC_VERSION) });
+    return canonicalHash({ ...workflow, spec_version: String(effectiveSpecVersion(workflow)) });
 }
 /** Hash of what the nodes were told: every resolved instruction, rule and context Source. */
 export function instructionHash(sources) {

package/dist/loader.js

@@ -14,6 +14,7 @@ import * as path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
 import { workflowZ, validateWorkflow, preflightLegacyVerify } from "./schema.js";
+import { approveDirectiveWarnings } from "./node-policy.js";
 import { DEFAULT_MIGRATION_CONFIG, migrateWorkflow, migrationWarning, } from "./migrations.js";
 /**
  * Load a workflow YAML or JSON file, parse with the canonical Zod schema,
@@ -57,6 +58,9 @@ export function validateParsed(raw, options = {}) {
     }
     raw = migrated.workflow;
     const warnings = migrated.applied.length > 0 ? [migrationWarning(migrated.from, migrated.to, options.filePath)] : [];
+    for (const note of migrated.notes)
+        if (note.warning)
+            warnings.push(note.warning);
     // Detect legacy `verify:` blocks (renamed to `eval:` in v0.2.0) before the
     // Zod parse. workflowZ is intentionally non-strict at the top level, so a
     // top-level `verify:` would be silently STRIPPED instead of surfacing the
@@ -93,5 +97,6 @@ export function validateParsed(raw, options = {}) {
             errors: structural.map((e) => ({ message: e.message, code: e.code, nodeId: e.nodeId })),
         };
     }
+    warnings.push(...approveDirectiveWarnings(parsed));
     return warnings.length > 0 ? { ok: true, workflow: parsed, warnings } : { ok: true, workflow: parsed };
 }

package/dist/migrations.d.ts

@@ -12,6 +12,11 @@
  *
  * Adding a migration: see `__tests__/migrations.test.ts` for the harness
  * (registry validity check plus a chain test to copy).
+ *
+ * A migration must keep behavior: a file migrated in memory runs exactly as it
+ * did. Where a new version changes a default, the migration writes the old
+ * default out explicitly, and reports each spot as a {@link MigrationNote}: the
+ * loader turns notes into warnings, `sweny workflow upgrade` into comments.
  */
 /** A raw, not-yet-validated workflow object as parsed from YAML or JSON. */
 export type RawWorkflow = Record<string, unknown>;
@@ -24,11 +29,35 @@ export interface Migration {
     description: string;
     /** Pure: must not mutate its input. Returns the next-version object. */
     migrate: (raw: RawWorkflow) => RawWorkflow;
+    /** Optional, pure: what the author should know about this step's changes to `raw` (its input). */
+    notes?: (raw: RawWorkflow) => MigrationNote[];
+}
+/** One spot a migration made explicit that the author should review. */
+export interface MigrationNote {
+    /** Path of the key the migration set, in the migrated object (e.g. `["nodes", "post", "permissions"]`). */
+    path: (string | number)[];
+    /** The node it is about, when there is one. */
+    nodeId?: string;
+    /** One line `sweny workflow upgrade` writes as a comment above `path`. */
+    comment: string;
+    /** One line the loader emits when it migrates in memory. Absent: nothing to warn about. */
+    warning?: string;
 }
 /** The spec version this build of sweny reads natively. */
-export declare const CURRENT_SPEC_VERSION = 1;
+export declare const CURRENT_SPEC_VERSION = 2;
+/**
+ * The spec version a workflow object runs as: its `spec_version`, or 1 when
+ * absent (a file written before the field, or a workflow built in code that
+ * the loader never migrated). Permission defaults and the journal's workflow
+ * hash both read this, so resume binds to the version the policy ran under.
+ */
+export declare function effectiveSpecVersion(workflow: {
+    spec_version?: string;
+}): number;
+/** The warning for one node that can write only because nothing limits it. */
+export declare function implicitWriteWarning(nodeId: string): string;
 /**
- * Ordered registry, one entry per version step. Empty while v1 is current.
+ * Ordered registry, one entry per version step.
  * Append only; never edit a shipped migration.
  */
 export declare const MIGRATIONS: readonly Migration[];
@@ -53,6 +82,8 @@ export type MigrateResult = {
     declared: boolean;
     /** Migrations applied, in order. Empty when the file is already current. */
     applied: Migration[];
+    /** Notes from the applied migrations, in order. Empty when there are none. */
+    notes: MigrationNote[];
 } | ({
     ok: false;
 } & MigrateError);

package/dist/migrations.js

@@ -12,14 +12,113 @@
  *
  * Adding a migration: see `__tests__/migrations.test.ts` for the harness
  * (registry validity check plus a chain test to copy).
+ *
+ * A migration must keep behavior: a file migrated in memory runs exactly as it
+ * did. Where a new version changes a default, the migration writes the old
+ * default out explicitly, and reports each spot as a {@link MigrationNote}: the
+ * loader turns notes into warnings, `sweny workflow upgrade` into comments.
  */
 /** The spec version this build of sweny reads natively. */
-export const CURRENT_SPEC_VERSION = 1;
+export const CURRENT_SPEC_VERSION = 2;
+/**
+ * The spec version a workflow object runs as: its `spec_version`, or 1 when
+ * absent (a file written before the field, or a workflow built in code that
+ * the loader never migrated). Permission defaults and the journal's workflow
+ * hash both read this, so resume binds to the version the policy ran under.
+ */
+export function effectiveSpecVersion(workflow) {
+    return workflow.spec_version === undefined ? 1 : Number(workflow.spec_version);
+}
+// ─── v1 -> v2: safe by default (#598) ────────────────────────────
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** The `access` a raw `permissions` value declares, if any. */
+function declaredAccess(p) {
+    if (typeof p === "string")
+        return p;
+    return isRecord(p) ? p.access : undefined;
+}
+function declaresNativeNone(p) {
+    return isRecord(p) && p.native === "none";
+}
+function skillList(node) {
+    return Array.isArray(node.skills) ? node.skills.filter((s) => typeof s === "string") : [];
+}
+/**
+ * Nodes whose access spec v1 left to its `write` fallback: no `access` of
+ * their own, no `outputs`, and no workflow `access`. Spec v2 reads those as
+ * `read`, so the migration declares what each one had.
+ *
+ * `read` only where it is provably the same: a node with no skills that runs
+ * with `native: none` (its own or the workflow's) has no tool at all, so
+ * nothing for `write` to unlock. Every other such node keeps `write`, the
+ * access it had; the migration never grants more than v1 did.
+ */
+function implicitAccessNodes(raw) {
+    if (declaredAccess(raw.permissions) !== undefined || !isRecord(raw.nodes))
+        return [];
+    const wfNone = declaresNativeNone(raw.permissions);
+    const found = [];
+    for (const [id, node] of Object.entries(raw.nodes)) {
+        if (!isRecord(node))
+            continue;
+        if (declaredAccess(node.permissions) !== undefined)
+            continue;
+        if (Array.isArray(node.outputs) && node.outputs.length > 0)
+            continue;
+        const skills = skillList(node);
+        const noTools = skills.length === 0 && (wfNone || declaresNativeNone(node.permissions));
+        const path = isRecord(node.permissions) ? ["nodes", id, "permissions", "access"] : ["nodes", id, "permissions"];
+        found.push({ id, access: noTools ? "read" : "write", path, skills });
+    }
+    return found;
+}
+/** The warning for one node that can write only because nothing limits it. */
+export function implicitWriteWarning(nodeId) {
+    return (`Node "${nodeId}" can write because nothing limits it (spec_version "1" default). ` +
+        "Declare permissions or outputs on it, or run `sweny workflow upgrade`.");
+}
+const v1ToV2 = {
+    from: 1,
+    to: 2,
+    description: "safe by default: declare `permissions` on every node that relied on the v1 `write` default",
+    migrate: (raw) => {
+        const found = implicitAccessNodes(raw);
+        if (found.length === 0)
+            return { ...raw };
+        const nodes = { ...raw.nodes };
+        for (const { id, access } of found) {
+            const node = nodes[id];
+            nodes[id] = {
+                ...node,
+                permissions: isRecord(node.permissions) ? { ...node.permissions, access } : access,
+            };
+        }
+        return { ...raw, nodes };
+    },
+    notes: (raw) => implicitAccessNodes(raw).map(({ id, access, path, skills }) => access === "read"
+        ? {
+            path,
+            nodeId: id,
+            comment: "sweny workflow upgrade: read, because this node has no skills and no built-in tools.",
+        }
+        : {
+            path,
+            nodeId: id,
+            comment: `sweny workflow upgrade: write, kept from spec v1 (nothing limited this node; ` +
+                (skills.length > 0
+                    ? `its skills [${skills.join(", ")}] may need their write tools). `
+                    : "it can use built-in shell and file edit tools). ") +
+                "If it only reads, set permissions: read; if it only posts, declare outputs.",
+            warning: implicitWriteWarning(id),
+        }),
+};
 /**
- * Ordered registry, one entry per version step. Empty while v1 is current.
+ * Ordered registry, one entry per version step.
  * Append only; never edit a shipped migration.
  */
-export const MIGRATIONS = [];
+export const MIGRATIONS = [v1ToV2];
 export const DEFAULT_MIGRATION_CONFIG = {
     current: CURRENT_SPEC_VERSION,
     migrations: MIGRATIONS,
@@ -65,12 +164,15 @@ export function migrateWorkflow(raw, config = DEFAULT_MIGRATION_CONFIG) {
     }
     let current = declared ? { ...raw, spec_version: String(from) } : raw;
     const applied = [];
+    const notes = [];
     for (let v = from; v < config.current; v++) {
         const step = config.migrations.find((m) => m.from === v);
         if (!step) {
             return { ok: false, code: "MIGRATION_FAILED", message: `No migration registered from spec_version "${v}".` };
         }
         try {
+            if (step.notes)
+                notes.push(...step.notes(current));
             current = { ...step.migrate(current), spec_version: String(step.to) };
         }
         catch (err) {
@@ -83,7 +185,7 @@ export function migrateWorkflow(raw, config = DEFAULT_MIGRATION_CONFIG) {
         }
         applied.push(step);
     }
-    return { ok: true, workflow: current, from, to: config.current, declared, applied };
+    return { ok: true, workflow: current, from, to: config.current, declared, applied, notes };
 }
 /** The single warning the loader emits when it migrated in memory. */
 export function migrationWarning(from, to, filePath) {

package/dist/node-policy.d.ts

@@ -12,15 +12,29 @@ export interface ResolvedPermissions {
     strict: boolean;
     native?: NodeNative;
 }
+/**
+ * The access a node gets when neither it nor the workflow declares one (#598).
+ * Spec v2 and later: `read`, safe by default. Spec v1, or no `spec_version` (a
+ * workflow built in code, or one the loader did not migrate): `write`, the v1
+ * behavior. The loader migrates v1 files to v2 with that `write` made explicit.
+ */
+export declare function defaultNodeAccess(workflow?: Pick<Workflow, "spec_version">): NodeAccess;
+/**
+ * True when the node runs under a declared policy: its own or the workflow's
+ * `permissions`, its `outputs`, or the spec v2 `read` default. A node that runs
+ * under none keeps each harness's own defaults (spec v1 only).
+ */
+export declare function hasNodePolicy(node: Pick<Node, "permissions" | "outputs">, workflow?: Pick<Workflow, "permissions" | "spec_version">): boolean;
 /**
  * Effective permissions for a node.
  *
  * access: the node's own, else `read` when it declares `outputs`, else the
- * workflow's, else `write` (today's behavior). A workflow `read` ceiling wins
- * over a node `write` (the loader rejects that combination; this is the
- * runtime backstop). deny: union. strict: either. native: `none` if either says so.
+ * workflow's, else {@link defaultNodeAccess} (`read` from spec v2, `write` in
+ * v1). A workflow `read` ceiling wins over a node `write` (the loader rejects
+ * that combination; this is the runtime backstop). deny: union. strict:
+ * either. native: `none` if either says so.
  */
-export declare function resolveNodePermissions(node: Pick<Node, "permissions" | "outputs">, workflow?: Pick<Workflow, "permissions">): ResolvedPermissions;
+export declare function resolveNodePermissions(node: Pick<Node, "permissions" | "outputs">, workflow?: Pick<Workflow, "permissions" | "spec_version">): ResolvedPermissions;
 /** True when a node asks for more than the workflow ceiling allows. */
 export declare function exceedsPermissionCeiling(node: Pick<Node, "permissions">, workflow: Pick<Workflow, "permissions">): boolean;
 /** The portable policy handed to the harness for one node run. */
@@ -30,3 +44,12 @@ export declare function buildNodePolicy(opts: {
     disallowedTools?: string[];
     egress?: string[];
 }): NodePolicy;
+/**
+ * Load warnings for review nodes told to approve (#598). The pr-review
+ * template before #598 said "If no issues found, approve with a brief note";
+ * files generated from it keep that line through `sweny workflow upgrade`.
+ * Precise on purpose: only a node that can write (so it could act on it), in a
+ * `pr_review` workflow or whose instruction is about a pull request or review,
+ * with an inline instruction line that says "approve", not negated ("never approve").
+ */
+export declare function approveDirectiveWarnings(workflow: Workflow): string[];

package/dist/node-policy.js

@@ -4,23 +4,45 @@
  * Pure and browser-safe. The workflow's `permissions` is both the default and
  * the ceiling for every node; a node may narrow it, never widen it.
  */
+import { effectiveSpecVersion } from "./migrations.js";
 function spec(p) {
     if (p === undefined)
         return {};
     return typeof p === "string" ? { access: p } : p;
 }
+/**
+ * The access a node gets when neither it nor the workflow declares one (#598).
+ * Spec v2 and later: `read`, safe by default. Spec v1, or no `spec_version` (a
+ * workflow built in code, or one the loader did not migrate): `write`, the v1
+ * behavior. The loader migrates v1 files to v2 with that `write` made explicit.
+ */
+export function defaultNodeAccess(workflow = {}) {
+    return effectiveSpecVersion(workflow) >= 2 ? "read" : "write";
+}
+/**
+ * True when the node runs under a declared policy: its own or the workflow's
+ * `permissions`, its `outputs`, or the spec v2 `read` default. A node that runs
+ * under none keeps each harness's own defaults (spec v1 only).
+ */
+export function hasNodePolicy(node, workflow = {}) {
+    return (node.permissions !== undefined ||
+        workflow.permissions !== undefined ||
+        (node.outputs?.length ?? 0) > 0 ||
+        defaultNodeAccess(workflow) === "read");
+}
 /**
  * Effective permissions for a node.
  *
  * access: the node's own, else `read` when it declares `outputs`, else the
- * workflow's, else `write` (today's behavior). A workflow `read` ceiling wins
- * over a node `write` (the loader rejects that combination; this is the
- * runtime backstop). deny: union. strict: either. native: `none` if either says so.
+ * workflow's, else {@link defaultNodeAccess} (`read` from spec v2, `write` in
+ * v1). A workflow `read` ceiling wins over a node `write` (the loader rejects
+ * that combination; this is the runtime backstop). deny: union. strict:
+ * either. native: `none` if either says so.
  */
 export function resolveNodePermissions(node, workflow = {}) {
     const wf = spec(workflow.permissions);
     const own = spec(node.permissions);
-    let access = own.access ?? (node.outputs && node.outputs.length > 0 ? "read" : (wf.access ?? "write"));
+    let access = own.access ?? (node.outputs && node.outputs.length > 0 ? "read" : (wf.access ?? defaultNodeAccess(workflow)));
     if (wf.access === "read")
         access = "read";
     const deny = [...new Set([...(wf.deny ?? []), ...(own.deny ?? [])])];
@@ -48,3 +70,36 @@ export function buildNodePolicy(opts) {
         ...(opts.permissions.native === "none" ? { nativeNone: true } : {}),
     };
 }
+const APPROVE = /\bapprove\b/i;
+/** "never approve", "do not approve", "don't ever approve": the negation governs approve itself. */
+const NEGATED = /(?:\b(?:never|not|no|nor)|n't)\s+(?:\w+\s+)?approve\b/i;
+const REVIEW = /\bpull requests?\b|\bPRs?\b|\breview/i;
+/**
+ * Load warnings for review nodes told to approve (#598). The pr-review
+ * template before #598 said "If no issues found, approve with a brief note";
+ * files generated from it keep that line through `sweny workflow upgrade`.
+ * Precise on purpose: only a node that can write (so it could act on it), in a
+ * `pr_review` workflow or whose instruction is about a pull request or review,
+ * with an inline instruction line that says "approve", not negated ("never approve").
+ */
+export function approveDirectiveWarnings(workflow) {
+    const warnings = [];
+    for (const [id, node] of Object.entries(workflow.nodes)) {
+        const text = typeof node.instruction === "string"
+            ? node.instruction
+            : "inline" in node.instruction
+                ? node.instruction.inline
+                : undefined;
+        if (text === undefined || resolveNodePermissions(node, workflow).access !== "write")
+            continue;
+        if (workflow.workflow_type !== "pr_review" && !REVIEW.test(text))
+            continue;
+        const line = text.split("\n").find((l) => APPROVE.test(l) && !NEGATED.test(l));
+        if (line === undefined)
+            continue;
+        warnings.push(`Node "${id}" can write and its instruction tells the agent to approve ("${line.trim()}"). ` +
+            "An AI reviewer should never approve: delete that line, and post the review as a comment output " +
+            "(see `sweny new --template pr-review`).");
+    }
+    return warnings;
+}

package/dist/safe-outputs.d.ts

@@ -13,7 +13,7 @@
  * labels, title prefix, dedupe, node cap, run cap. An optional model screen runs last
  * over the intents that passed and can only veto them.
  */
-import type { BranchPusher, Logger, SafeOutputDeclaration, SafeOutputPin, SafeOutputReceipt, SafeOutputsPolicy, SafeOutputType, Skill, Tool, ToolContext } from "./types.js";
+import type { BranchPusher, Logger, SafeOutputDeclaration, SafeOutputPin, SafeOutputTarget, SafeOutputReceipt, SafeOutputsPolicy, SafeOutputType, Skill, Tool, ToolContext } from "./types.js";
 /** Name of the intent-recording tool a node with `outputs` receives. */
 export declare const EMIT_OUTPUT_TOOL = "emit_output";
 /** Longest title the write stage accepts (after the prefix). */
@@ -60,6 +60,8 @@ export declare function actorTrusted(policy: SafeOutputsPolicy | undefined, acto
  * The issue or PR a declaration pins, as a string. `{ input: name }` reads the
  * run input; an absent or empty value is `undefined`, which refuses the write.
  */
+/** A declared target: the literal, or the run input it names. Empty or missing: undefined. */
+export declare function resolveTarget(target: SafeOutputTarget | undefined, input?: Record<string, unknown>): string | undefined;
 export declare function resolvePin(pin: SafeOutputPin, input?: Record<string, unknown>): string | undefined;
 /** `30m` → 1_800_000. Undefined for anything the schema would reject. */
 export declare function parseDuration(s: string | undefined): number | undefined;