@sweny-ai/core 0.1.210 → 0.1.211

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;

package/dist/safe-outputs.js

@@ -113,8 +113,9 @@ export function createEmitOutputTool(declarations, buffer, now = Date.now) {
 export function safeOutputsInstruction(declarations, input) {
     const lines = declarations.map((d) => {
         const parts = [`at most ${d.max ?? 1}`];
-        if (d.target)
-            parts.push(`target ${d.target}`);
+        const target = resolveTarget(d.target, input);
+        if (target)
+            parts.push(`target ${target}`);
         if (d.number !== undefined) {
             const pin = resolvePin(d.number, input);
             parts.push(pin ? `only issue or PR ${pin} (the number may be omitted)` : "pinned issue not set for this run");
@@ -179,6 +180,14 @@ export function actorTrusted(policy, actor) {
  * 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 function resolveTarget(target, input) {
+    const raw = typeof target === "object" ? input?.[target.input] : target;
+    if (typeof raw !== "string")
+        return undefined;
+    const v = raw.trim();
+    return v.length > 0 ? v : undefined;
+}
 export function resolvePin(pin, input) {
     const raw = typeof pin === "object" ? input?.[pin.input] : pin;
     if (typeof raw === "number" && Number.isInteger(raw) && raw > 0)
@@ -375,12 +384,21 @@ export async function applySafeOutputs(o) {
             refuse("no skill can apply this type");
             continue;
         }
-        // The run's repo from the operator's env, never one a workspace .env introduced.
-        const pinned = decl.target ?? (via === "github" ? trustedEnvValue(o.env, "GITHUB_REPOSITORY") || undefined : undefined);
+        // The declared target (a literal, or the run input it names), else the run's
+        // repo from the operator's env, never one a workspace .env introduced.
+        const pinned = resolveTarget(decl.target, o.input) ??
+            (via === "github" ? trustedEnvValue(o.env, "GITHUB_REPOSITORY") || undefined : undefined);
         if (intent.target && pinned && intent.target.toLowerCase() !== pinned.toLowerCase()) {
             refuse("target outside the declared target", { via });
             continue;
         }
+        // #598: an output pinned to one issue or PR is pinned to one repository too, and that
+        // repository comes only from the declaration, a run input, or GITHUB_REPOSITORY. Never
+        // from the agent: PR #N of any repo the token can write to is not the pinned PR.
+        if (via === "github" && decl.number !== undefined && !pinned) {
+            refuse("pinned output needs a trusted repository", { via });
+            continue;
+        }
         const target = intent.target ?? pinned;
         if (applier.needsTarget && !target) {
             refuse("no target", { via });

package/dist/schema.d.ts

@@ -297,7 +297,9 @@ export declare const safeOutputDeclarationZ: z.ZodObject<{
     }>;
     via: z.ZodOptional<z.ZodString>;
     max: z.ZodOptional<z.ZodNumber>;
-    target: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        input: z.ZodString;
+    }, z.core.$strict>]>>;
     title_prefix: z.ZodOptional<z.ZodString>;
     labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     expires: z.ZodOptional<z.ZodString>;
@@ -397,7 +399,9 @@ export declare const nodeZ: z.ZodObject<{
         }>;
         via: z.ZodOptional<z.ZodString>;
         max: z.ZodOptional<z.ZodNumber>;
-        target: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            input: z.ZodString;
+        }, z.core.$strict>]>>;
         title_prefix: z.ZodOptional<z.ZodString>;
         labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
         expires: z.ZodOptional<z.ZodString>;
@@ -603,7 +607,9 @@ export declare const workflowZ: z.ZodObject<{
             }>;
             via: z.ZodOptional<z.ZodString>;
             max: z.ZodOptional<z.ZodNumber>;
-            target: z.ZodOptional<z.ZodString>;
+            target: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                input: z.ZodString;
+            }, z.core.$strict>]>>;
             title_prefix: z.ZodOptional<z.ZodString>;
             labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
             expires: z.ZodOptional<z.ZodString>;
@@ -871,7 +877,9 @@ export declare function parseWorkflow(raw: unknown): {
             type: "label" | "comment" | "issue" | "pr" | "issue_state";
             via?: string | undefined;
             max?: number | undefined;
-            target?: string | undefined;
+            target?: string | {
+                input: string;
+            } | undefined;
             title_prefix?: string | undefined;
             labels?: string[] | undefined;
             expires?: string | undefined;
@@ -1360,9 +1368,21 @@ export declare const workflowJsonSchema: {
                     readonly description: "Max writes of this type from this node per run. Default 1.";
                 };
                 readonly target: {
-                    readonly type: "string";
-                    readonly minLength: 1;
-                    readonly description: "Pinned target (GitHub owner/repo, Linear team id). GitHub default: GITHUB_REPOSITORY.";
+                    readonly description: "Pinned target (GitHub owner/repo, Linear team id), or { input: <name> } to take it from a run input. GitHub default: GITHUB_REPOSITORY. An output that pins number never takes its GitHub repository from the agent.";
+                    readonly oneOf: readonly [{
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    }, {
+                        readonly type: "object";
+                        readonly required: readonly ["input"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly input: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                    }];
                 };
                 readonly title_prefix: {
                     readonly type: "string";
@@ -1427,7 +1447,7 @@ export declare const workflowJsonSchema: {
         readonly spec_version: {
             readonly type: "string";
             readonly pattern: "^[1-9][0-9]*$";
-            readonly description: "Workflow spec version as a positive integer string. Absent means 1. Older versions are migrated in memory on load; newer than the CLI supports is refused. Run `sweny workflow upgrade <file>` to rewrite a file at the current version.";
+            readonly description: "Workflow spec version as a positive integer string. Absent means 1. Version 2 is safe by default: a node that declares no permissions and no outputs, in a workflow that declares no permissions, is read-only. Version 1 files are migrated in memory on load, keeping write on such nodes with one warning each; newer than the CLI supports is refused. Run `sweny workflow upgrade <file>` to rewrite a file at the current version.";
         };
         readonly entry: {
             readonly type: "string";
@@ -1465,7 +1485,7 @@ export declare const workflowJsonSchema: {
         };
         readonly permissions: {
             readonly $ref: "#/$defs/Permissions";
-            readonly description: "Default and ceiling for every node's permissions. Absent: write.";
+            readonly description: "Default and ceiling for every node's permissions. Absent: read (spec_version 2), write (spec_version 1).";
         };
         readonly safe_outputs: {
             readonly type: "object";
@@ -1759,7 +1779,7 @@ export declare const workflowJsonSchema: {
                     };
                     readonly permissions: {
                         readonly $ref: "#/$defs/Permissions";
-                        readonly description: "What this node's agent may do. Absent: read when the node declares outputs, else the workflow's permissions, else write.";
+                        readonly description: "What this node's agent may do. Absent: read when the node declares outputs, else the workflow's permissions, else read (spec_version 2) or write (spec_version 1).";
                     };
                     readonly outputs: {
                         readonly type: "array";

package/dist/schema.js

@@ -303,7 +303,7 @@ export const safeOutputDeclarationZ = z
     type: z.enum(SAFE_OUTPUT_TYPES),
     via: z.string().min(1).optional(),
     max: z.number().int().min(1).max(SAFE_OUTPUT_MAX_CEILING).optional(),
-    target: z.string().min(1).optional(),
+    target: z.union([z.string().min(1), z.object({ input: z.string().min(1) }).strict()]).optional(),
     title_prefix: z.string().min(1).max(64).optional(),
     labels: z.array(z.string().min(1)).min(1).optional(),
     expires: z.string().regex(SAFE_OUTPUT_EXPIRES_PATTERN).optional(),
@@ -1073,9 +1073,16 @@ export const workflowJsonSchema = {
                     description: "Max writes of this type from this node per run. Default 1.",
                 },
                 target: {
-                    type: "string",
-                    minLength: 1,
-                    description: "Pinned target (GitHub owner/repo, Linear team id). GitHub default: GITHUB_REPOSITORY.",
+                    description: "Pinned target (GitHub owner/repo, Linear team id), or { input: <name> } to take it from a run input. GitHub default: GITHUB_REPOSITORY. An output that pins number never takes its GitHub repository from the agent.",
+                    oneOf: [
+                        { type: "string", minLength: 1 },
+                        {
+                            type: "object",
+                            required: ["input"],
+                            additionalProperties: false,
+                            properties: { input: { type: "string", minLength: 1 } },
+                        },
+                    ],
                 },
                 title_prefix: {
                     type: "string",
@@ -1122,7 +1129,7 @@ export const workflowJsonSchema = {
         spec_version: {
             type: "string",
             pattern: "^[1-9][0-9]*$",
-            description: "Workflow spec version as a positive integer string. Absent means 1. Older versions are migrated in memory on load; newer than the CLI supports is refused. Run `sweny workflow upgrade <file>` to rewrite a file at the current version.",
+            description: "Workflow spec version as a positive integer string. Absent means 1. Version 2 is safe by default: a node that declares no permissions and no outputs, in a workflow that declares no permissions, is read-only. Version 1 files are migrated in memory on load, keeping write on such nodes with one warning each; newer than the CLI supports is refused. Run `sweny workflow upgrade <file>` to rewrite a file at the current version.",
         },
         entry: { type: "string", minLength: 1, description: "ID of the entry node" },
         rules: {
@@ -1155,7 +1162,7 @@ export const workflowJsonSchema = {
         },
         permissions: {
             $ref: "#/$defs/Permissions",
-            description: "Default and ceiling for every node's permissions. Absent: write.",
+            description: "Default and ceiling for every node's permissions. Absent: read (spec_version 2), write (spec_version 1).",
         },
         safe_outputs: {
             type: "object",
@@ -1374,7 +1381,7 @@ export const workflowJsonSchema = {
                     },
                     permissions: {
                         $ref: "#/$defs/Permissions",
-                        description: "What this node's agent may do. Absent: read when the node declares outputs, else the workflow's permissions, else write.",
+                        description: "What this node's agent may do. Absent: read when the node declares outputs, else the workflow's permissions, else read (spec_version 2) or write (spec_version 1).",
                     },
                     outputs: {
                         type: "array",

package/dist/types.d.ts

@@ -502,7 +502,7 @@ export interface Node {
      * only `access: "read"` skill tools, no external skill MCP servers, no
      * shell / file-write / edit / fetch / subagent built-ins. Absent: `read`
      * when the node declares `outputs`, else the workflow's `permissions`,
-     * else `write` (today's behavior).
+     * else `read` from spec_version 2, `write` in spec_version 1 (#598).
      */
     permissions?: NodePermissions;
     /**
@@ -561,8 +561,12 @@ export interface SafeOutputDeclaration {
     via?: string;
     /** Max writes of this type from this node per run. Default 1. */
     max?: number;
-    /** Pinned target (GitHub `owner/repo`, Linear team id). GitHub default: `GITHUB_REPOSITORY`. */
-    target?: string;
+    /**
+     * Pinned target (GitHub `owner/repo`, Linear team id), or `{ input: <name> }`
+     * to take it from a run input. GitHub default: `GITHUB_REPOSITORY`. An output
+     * pinned to an issue (`number`) never takes its GitHub repository from the agent (#598).
+     */
+    target?: SafeOutputTarget;
     /** Prepended to issue / PR titles that do not already start with it. */
     title_prefix?: string;
     /** issue / pr: labels always added. label: the only labels the agent may add. */
@@ -580,6 +584,10 @@ export interface SafeOutputDeclaration {
     /** issue_state only: the one change this output may make. Default: either. */
     state?: SafeOutputState;
 }
+/** A pinned target: a literal (`owner/repo`, team id), or the name of a run input that holds one. */
+export type SafeOutputTarget = string | {
+    input: string;
+};
 /** A pinned issue / PR: a literal number or identifier, or the name of a run input that holds one. */
 export type SafeOutputPin = string | number | {
     input: string;
@@ -733,7 +741,10 @@ export interface Workflow {
      * See `src/inputs.ts` for the field shape and validation rules.
      */
     inputs?: import("./inputs.js").WorkflowInputs;
-    /** Default and ceiling for every node's `permissions` (#365). Absent: `write`. */
+    /**
+     * Default and ceiling for every node's `permissions` (#365). Absent: `read`
+     * from spec_version 2, `write` in spec_version 1 (#598).
+     */
     permissions?: NodePermissions;
     /** Workflow-level safe-output policy (#365). */
     safe_outputs?: SafeOutputsPolicy;

package/dist/workflow-builder.d.ts

@@ -26,7 +26,7 @@ export declare function buildSystemPrompt(skills: Skill[], existingWorkflow?: Wo
  * adds a `summary` key from the text response. We strip `summary`
  * and any other non-workflow keys before parsing.
  */
-export declare function extractWorkflow(data: Record<string, unknown>): Workflow;
+export declare function extractWorkflow(data: Record<string, unknown>, keep?: Pick<Workflow, "spec_version">): Workflow;
 /**
  * Derive the required environment variables for a workflow from its skills.
  * Deterministic — doesn't depend on Claude generating a variables block.

package/dist/workflow-builder.js

@@ -6,6 +6,7 @@
  * description and available skills, and returns a validated Workflow.
  */
 import { workflowZ, validateWorkflow, workflowJsonSchema } from "./schema.js";
+import { CURRENT_SPEC_VERSION } from "./migrations.js";
 // ─── Instruction quality guidance ────────────────────────────────
 const INSTRUCTION_GUIDANCE = `Each node's \`instruction\` field is a detailed prompt that Claude will execute autonomously.
 Write instructions as if briefing a skilled engineer who has access to the node's tools
@@ -60,6 +61,7 @@ export function buildSystemPrompt(skills, existingWorkflow) {
         "- Use a natural-language `when` only for a fuzzy condition no declared field can express",
         "- Put safety conditions (anything that gates a write, a PR or an issue) in expressions, never in natural language",
         "- Every node must be reachable from the entry node",
+        "- Nodes are read-only unless they declare otherwise (spec_version 2). A node that files issues, comments or opens PRs declares `outputs` (comment, issue, pr, label, issue_state) and stays read-only; any other node that must change something declares `permissions: write`, narrowed with `deny` to the built-in tool classes it does not need",
         "- Return ONLY the workflow JSON object — no markdown fences, no explanation",
     ];
     if (existingWorkflow) {
@@ -73,9 +75,14 @@ export function buildSystemPrompt(skills, existingWorkflow) {
  * adds a `summary` key from the text response. We strip `summary`
  * and any other non-workflow keys before parsing.
  */
-export function extractWorkflow(data) {
-    // Remove keys added by ClaudeClient that aren't part of the workflow schema
-    const { summary: _summary, ...rest } = data;
+export function extractWorkflow(data, keep) {
+    // Remove keys added by ClaudeClient that aren't part of the workflow schema.
+    // The spec version is ours to set, never the model's (#598): a new workflow is
+    // current (read-only by default), a refined one keeps the version it had.
+    const { summary: _summary, spec_version: _modelVersion, ...body } = data;
+    // `keep` (a refine) holds the version the workflow had, possibly none; a build gets the current one.
+    const specVersion = keep ? keep.spec_version : String(CURRENT_SPEC_VERSION);
+    const rest = specVersion === undefined ? body : { spec_version: specVersion, ...body };
     // workflowZ.parse throws a ZodError on invalid input
     const parsed = workflowZ.parse(rest);
     const errors = validateWorkflow(parsed);
@@ -158,5 +165,5 @@ export async function refineWorkflow(workflow, instruction, options) {
     if (result.status === "failed") {
         throw new Error(`Claude failed to refine workflow: ${result.data.error ?? "unknown error"}`);
     }
-    return extractWorkflow(result.data);
+    return extractWorkflow(result.data, { spec_version: workflow.spec_version });
 }