@mrciphersmith/keryx 0.2.154 → 0.2.156

package/dist/proxy-worker.js

@@ -6,6 +6,147 @@ import { parentPort, workerData } from "worker_threads";
 import http from "http";
 import https from "https";
 import net from "net";
+import dns from "dns";
+import { unlinkSync } from "fs";
+
+// src/harness/policy/engine.ts
+var HARD_DENY_RISKS = new Set([
+  "write",
+  "shell",
+  "network",
+  "delegate"
+]);
+
+// src/harness/mutation/guard.ts
+var MAX_U32 = 4294967295;
+function u32ToOctets(n) {
+  return [n >>> 24 & 255, n >>> 16 & 255, n >>> 8 & 255, n & 255];
+}
+function isPrivateIPv4(o0, o1, o2, o3) {
+  if (o0 === 0 && o1 === 0 && o2 === 0 && o3 === 0)
+    return true;
+  if (o0 === 127)
+    return true;
+  if (o0 === 10)
+    return true;
+  if (o0 === 172 && o1 >= 16 && o1 <= 31)
+    return true;
+  if (o0 === 192 && o1 === 168)
+    return true;
+  if (o0 === 169 && o1 === 254)
+    return true;
+  if (o0 === 100 && o1 >= 64 && o1 <= 127)
+    return true;
+  return false;
+}
+function isPrivateOrReservedAddress(ip) {
+  const v4 = ip.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (v4 !== null) {
+    const octets = [v4[1], v4[2], v4[3], v4[4]].map((s) => Number(s));
+    if (octets.some((o) => o > 255))
+      return true;
+    return isPrivateIPv4(octets[0], octets[1], octets[2], octets[3]);
+  }
+  const stripped = ip.replace(/^\[|\]$/g, "").toLowerCase();
+  const mapped = stripped.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (mapped !== null)
+    return isPrivateOrReservedAddress(mapped[1]);
+  const nat64Hex = stripped.match(/^64:ff9b::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (nat64Hex !== null) {
+    const hi = parseInt(nat64Hex[1], 16);
+    const lo = parseInt(nat64Hex[2], 16);
+    return isPrivateOrReservedAddress(`${hi >>> 8 & 255}.${hi & 255}.${lo >>> 8 & 255}.${lo & 255}`);
+  }
+  const nat64Mixed = stripped.match(/^64:ff9b::(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (nat64Mixed !== null)
+    return isPrivateOrReservedAddress(nat64Mixed[1]);
+  if (/^64:ff9b:1:/.test(stripped))
+    return true;
+  if (stripped === "::1" || stripped === "::" || stripped === "0:0:0:0:0:0:0:1" || stripped === "0:0:0:0:0:0:0:0")
+    return true;
+  if (/^fe[89ab][0-9a-f]:/.test(stripped))
+    return true;
+  if (/^f[cd][0-9a-f]{2}:/.test(stripped))
+    return true;
+  return false;
+}
+function parseFlatInt(s) {
+  let value;
+  if (/^0x[0-9a-f]+$/i.test(s))
+    value = parseInt(s.slice(2), 16);
+  else if (/^0[0-7]+$/.test(s))
+    value = parseInt(s.slice(1), 8);
+  else if (/^[0-9]+$/.test(s))
+    value = parseInt(s, 10);
+  else
+    return null;
+  if (!Number.isFinite(value) || value < 0 || value > MAX_U32)
+    return null;
+  return value;
+}
+function decodeDottedIPv4(s) {
+  const parts = s.split(".");
+  if (parts.length < 2 || parts.length > 4)
+    return null;
+  const nums = [];
+  for (const part of parts) {
+    const v = parseFlatInt(part);
+    if (v === null)
+      return null;
+    nums.push(v);
+  }
+  if (parts.length === 4) {
+    if (nums.some((x) => x > 255))
+      return null;
+    return [nums[0], nums[1], nums[2], nums[3]];
+  }
+  if (parts.length === 3) {
+    const [a, b, c] = nums;
+    if (a > 255 || b > 255 || c > 65535)
+      return null;
+    return [a, b, c >>> 8 & 255, c & 255];
+  }
+  const [a, b] = nums;
+  if (a > 255 || b > 16777215)
+    return null;
+  return [a, b >>> 16 & 255, b >>> 8 & 255, b & 255];
+}
+function looksLikeIpHost(host) {
+  const stripped = host.replace(/^\[|\]$/g, "");
+  if (stripped.includes(":"))
+    return true;
+  if (decodeEncodedIPv4(stripped) !== null)
+    return true;
+  const labels = stripped.split(".");
+  const last = labels[labels.length - 1] ?? "";
+  if (/^\d+$/.test(last) || /^0x[0-9a-f]+$/i.test(last))
+    return true;
+  return false;
+}
+function decodeEncodedIPv4(candidate) {
+  const mapped = /::ffff:(.+)$/i.exec(candidate);
+  if (mapped) {
+    const tail = mapped[1];
+    if (tail.includes("."))
+      return decodeDottedIPv4(tail);
+    const groups = tail.split(":");
+    if (groups.length === 2 && /^[0-9a-f]{1,4}$/i.test(groups[0]) && /^[0-9a-f]{1,4}$/i.test(groups[1])) {
+      const n = parseInt(groups[0], 16) * 65536 + parseInt(groups[1], 16);
+      if (n <= MAX_U32)
+        return u32ToOctets(n);
+    }
+    return null;
+  }
+  if (candidate.includes("."))
+    return decodeDottedIPv4(candidate);
+  const n = parseFlatInt(candidate);
+  if (n === null)
+    return null;
+  return u32ToOctets(n);
+}
+var ENV_DUMP_ARGV = new Set(["env", "printenv"]);
+
+// src/harness/process/sandbox/proxy.ts
 function normalizeHost(host) {
   return host.toLowerCase().replace(/\.$/, "");
 }
@@ -27,6 +168,43 @@ function matchesAllowlist(host, allowed) {
   }
   return false;
 }
+function parsePort(raw) {
+  if (raw === undefined || !/^[1-9][0-9]{0,4}$/.test(raw))
+    return;
+  const n = Number(raw);
+  return n >= 1 && n <= 65535 ? n : undefined;
+}
+function portAllowed(port, kind, allowedPorts) {
+  if (allowedPorts !== undefined && allowedPorts.length > 0)
+    return allowedPorts.includes(port);
+  return kind === "connect" ? port === 443 : port === 80;
+}
+function trySync(make, onError) {
+  try {
+    return make();
+  } catch {
+    onError();
+    return;
+  }
+}
+async function defaultResolveHost(hostname) {
+  try {
+    const { address } = await dns.promises.lookup(hostname);
+    return address;
+  } catch {
+    return;
+  }
+}
+async function checkedAddress(hostname, resolveHost) {
+  if (looksLikeIpHost(hostname))
+    return { reason: "IP-literal targets are refused \u2014 the allowlist is domains only" };
+  const address = await resolveHost(hostname);
+  if (address === undefined)
+    return { reason: "could not be resolved" };
+  if (isPrivateOrReservedAddress(address))
+    return { reason: `resolved to ${address}, a loopback/private/link-local/metadata address` };
+  return { address };
+}
 function substituteValue(value, masks) {
   if (value === undefined)
     return;
@@ -53,57 +231,107 @@ function httpTarget(req) {
   try {
     if (/^https?:\/\//i.test(raw)) {
       const u = new URL(raw);
-      return { hostname: u.hostname, port: u.port ? Number(u.port) : 80 };
+      if (u.hostname.length === 0)
+        return { kind: "no-target" };
+      if (u.port.length === 0)
+        return { kind: "ok", hostname: u.hostname, port: 80 };
+      const port = parsePort(u.port);
+      return port === undefined ? { kind: "invalid-port", hostname: u.hostname } : { kind: "ok", hostname: u.hostname, port };
     }
   } catch {}
   const hostHeader = req.headers.host;
-  if (hostHeader) {
-    const [hostname, port] = hostHeader.split(":");
-    if (hostname)
-      return { hostname, port: port ? Number(port) : 80 };
+  if (hostHeader !== undefined && hostHeader.length > 0) {
+    const colon = hostHeader.lastIndexOf(":");
+    const hostname = colon === -1 ? hostHeader : hostHeader.slice(0, colon);
+    const portRaw = colon === -1 ? undefined : hostHeader.slice(colon + 1);
+    if (hostname.length === 0)
+      return { kind: "no-target" };
+    if (portRaw === undefined || portRaw.length === 0)
+      return { kind: "ok", hostname, port: 80 };
+    const port = parsePort(portRaw);
+    return port === undefined ? { kind: "invalid-port", hostname } : { kind: "ok", hostname, port };
   }
-  return;
+  return { kind: "no-target" };
 }
 async function createAllowlistProxy(opts) {
   const host = opts.host ?? "127.0.0.1";
   const allowed = opts.allowedDomains;
+  const hardened = opts.refuseReservedAddresses === true;
+  const portRestricted = hardened || opts.allowedPorts !== undefined && opts.allowedPorts.length > 0;
+  const resolveHost = opts.resolveHost ?? defaultResolveHost;
   const decide = (d) => {
-    opts.onDecision?.(d);
+    opts.onDecision?.({ ...d, at: new Date().toISOString() });
     return d.allowed;
   };
   const server = http.createServer((req, res) => {
     const target = httpTarget(req);
-    const hostname = target?.hostname ?? "";
-    if (!target || !decide({ host: hostname, allowed: matchesAllowlist(hostname, allowed), kind: "http" })) {
+    const hostname = target.kind === "no-target" ? "" : target.hostname;
+    const refuse = (reason) => {
+      decide({ host: hostname, allowed: false, kind: "http", ...target.kind === "ok" ? { port: target.port } : {}, reason });
       res.writeHead(403, { "content-type": "text/plain" });
       res.end("blocked by keryx sandbox network allowlist");
+    };
+    if (target.kind === "no-target") {
+      refuse("no target host");
       return;
     }
-    const headers = applyMasks(req.headers, opts.masks ?? [], target.hostname);
-    const upstream = http.request({ host: target.hostname, port: target.port, method: req.method, path: pathFromUrl(req.url), headers }, (up) => {
-      res.writeHead(up.statusCode ?? 502, up.headers);
-      up.pipe(res);
-    });
-    upstream.on("error", () => {
-      if (!res.headersSent)
-        res.writeHead(502);
-      res.end("upstream error");
+    if (target.kind === "invalid-port") {
+      refuse("invalid port");
+      return;
+    }
+    if (!matchesAllowlist(hostname, allowed)) {
+      refuse("not on the allowlist");
+      return;
+    }
+    if (portRestricted && !portAllowed(target.port, "http", opts.allowedPorts)) {
+      refuse(`port ${target.port} is not allowed`);
+      return;
+    }
+    const proceed = (connectHost) => {
+      decide({ host: hostname, allowed: true, kind: "http", port: target.port });
+      const headers = applyMasks(req.headers, opts.masks ?? [], target.hostname);
+      const upstream = trySync(() => http.request({ host: connectHost, port: target.port, method: req.method, path: pathFromUrl(req.url), headers: { ...headers, host: target.hostname } }, (up) => {
+        res.writeHead(up.statusCode ?? 502, up.headers);
+        up.pipe(res);
+      }), () => {
+        if (!res.headersSent)
+          res.writeHead(502);
+        res.end("upstream error");
+      });
+      if (upstream === undefined)
+        return;
+      upstream.on("error", () => {
+        if (!res.headersSent)
+          res.writeHead(502);
+        res.end("upstream error");
+      });
+      req.pipe(upstream);
+    };
+    if (!hardened) {
+      proceed(target.hostname);
+      return;
+    }
+    checkedAddress(target.hostname, resolveHost).then((checked) => {
+      if ("reason" in checked)
+        refuse(checked.reason);
+      else
+        proceed(checked.address);
     });
-    req.pipe(upstream);
   });
   const makeMitmHandler = (pinnedHost, pinnedPort) => (req, res) => {
     const hostHeader = req.headers.host ?? "";
-    const [rawHost, rawPort] = hostHeader.split(":");
-    const hostname = rawHost ?? "";
-    const upstreamPort = rawPort ? Number(rawPort) : pinnedPort;
-    const permitted = matchesAllowlist(hostname, allowed) && normalizeHost(hostname) === pinnedHost && upstreamPort === pinnedPort;
-    if (!decide({ host: hostname, allowed: permitted, kind: "http" })) {
+    const colon = hostHeader.lastIndexOf(":");
+    const hostname = colon === -1 ? hostHeader : hostHeader.slice(0, colon);
+    const rawPort = colon === -1 ? undefined : hostHeader.slice(colon + 1);
+    const upstreamPort = rawPort === undefined || rawPort.length === 0 ? pinnedPort : parsePort(rawPort);
+    const permitted = upstreamPort !== undefined && matchesAllowlist(hostname, allowed) && normalizeHost(hostname) === pinnedHost && upstreamPort === pinnedPort;
+    if (!decide({ host: hostname, allowed: permitted, kind: "http", ...upstreamPort !== undefined ? { port: upstreamPort } : {} })) {
       res.writeHead(403, { "content-type": "text/plain" });
       res.end("blocked by keryx sandbox network allowlist");
       return;
     }
     const headers = applyMasks(req.headers, opts.masks ?? [], hostname);
-    const upstreamReq = https.request({
+    const upstreamReq = trySync(() => https.request({
       host: hostname,
       port: upstreamPort,
       method: req.method,
@@ -114,7 +342,13 @@ async function createAllowlistProxy(opts) {
     }, (up) => {
       res.writeHead(up.statusCode ?? 502, up.headers);
       up.pipe(res);
+    }), () => {
+      if (!res.headersSent)
+        res.writeHead(502);
+      res.end("upstream error");
     });
+    if (upstreamReq === undefined)
+      return;
     upstreamReq.on("error", () => {
       if (!res.headersSent)
         res.writeHead(502);
@@ -138,64 +372,105 @@ async function createAllowlistProxy(opts) {
     return port;
   };
   server.on("connect", (req, clientSocket, head) => {
-    const [reqHost, reqPort] = (req.url ?? "").split(":");
-    const hostname = reqHost ?? "";
-    const port = Number(reqPort) || 443;
-    if (!decide({ host: hostname, allowed: matchesAllowlist(hostname, allowed), kind: "connect" })) {
+    const url = req.url ?? "";
+    const colon = url.lastIndexOf(":");
+    const hostname = colon === -1 ? url : url.slice(0, colon);
+    const portRaw = colon === -1 ? undefined : url.slice(colon + 1);
+    const parsedPort = portRaw === undefined || portRaw.length === 0 ? 443 : parsePort(portRaw);
+    const refuse = (reason) => {
+      decide({ host: hostname, allowed: false, kind: "connect", ...parsedPort !== undefined ? { port: parsedPort } : {}, reason });
       clientSocket.write(`HTTP/1.1 403 Forbidden\r
 \r
 `);
       clientSocket.end();
+    };
+    if (parsedPort === undefined) {
+      refuse("invalid port");
+      return;
+    }
+    const port = parsedPort;
+    if (!matchesAllowlist(hostname, allowed)) {
+      refuse("not on the allowlist");
       return;
     }
-    const ca = opts.tlsTerminate;
-    if (ca) {
-      (async () => {
-        try {
-          const terminatorPort = await mitmPortFor(hostname, port, ca);
-          clientSocket.write(`HTTP/1.1 200 Connection Established\r
+    if (portRestricted && !portAllowed(port, "connect", opts.allowedPorts)) {
+      refuse(`port ${port} is not allowed`);
+      return;
+    }
+    const proceed = (connectHost) => {
+      decide({ host: hostname, allowed: true, kind: "connect", port });
+      const ca = opts.tlsTerminate;
+      if (ca) {
+        (async () => {
+          try {
+            const terminatorPort = await mitmPortFor(hostname, port, ca);
+            clientSocket.write(`HTTP/1.1 200 Connection Established\r
 \r
 `);
-          const internal = net.connect(terminatorPort, "127.0.0.1", () => {
-            if (head && head.length > 0)
-              internal.write(head);
-            clientSocket.pipe(internal);
-            internal.pipe(clientSocket);
-          });
-          internal.on("error", () => clientSocket.destroy());
-          clientSocket.on("error", () => internal.destroy());
-        } catch {
-          clientSocket.write(`HTTP/1.1 502 Bad Gateway\r
+            const internal = net.connect(terminatorPort, "127.0.0.1", () => {
+              if (head && head.length > 0)
+                internal.write(head);
+              clientSocket.pipe(internal);
+              internal.pipe(clientSocket);
+            });
+            internal.on("error", () => clientSocket.destroy());
+            clientSocket.on("error", () => internal.destroy());
+          } catch {
+            clientSocket.write(`HTTP/1.1 502 Bad Gateway\r
 \r
 `);
-          clientSocket.end();
-        }
-      })();
-      return;
-    }
-    const upstream = net.connect(port, hostname, () => {
-      clientSocket.write(`HTTP/1.1 200 Connection Established\r
+            clientSocket.end();
+          }
+        })();
+        return;
+      }
+      const onUpstreamConnect = (upstream) => {
+        clientSocket.write(`HTTP/1.1 200 Connection Established\r
 \r
 `);
-      if (head && head.length > 0)
-        upstream.write(head);
-      upstream.pipe(clientSocket);
-      clientSocket.pipe(upstream);
-    });
-    upstream.on("error", () => {
-      clientSocket.write(`HTTP/1.1 502 Bad Gateway\r
+        if (head && head.length > 0)
+          upstream.write(head);
+        upstream.pipe(clientSocket);
+        clientSocket.pipe(upstream);
+      };
+      const onUpstreamFailure = () => {
+        clientSocket.write(`HTTP/1.1 502 Bad Gateway\r
 \r
 `);
-      clientSocket.end();
+        clientSocket.end();
+      };
+      const upstream = trySync(() => net.connect(port, connectHost), onUpstreamFailure);
+      if (upstream === undefined)
+        return;
+      upstream.once("connect", () => onUpstreamConnect(upstream));
+      upstream.on("error", onUpstreamFailure);
+      clientSocket.on("error", () => upstream.destroy());
+    };
+    if (!hardened) {
+      proceed(hostname);
+      return;
+    }
+    checkedAddress(hostname, resolveHost).then((checked) => {
+      if ("reason" in checked)
+        refuse(checked.reason);
+      else
+        proceed(checked.address);
     });
-    clientSocket.on("error", () => upstream.destroy());
   });
-  await new Promise((resolve) => server.listen(opts.port ?? 0, host, () => resolve()));
+  if (opts.unixSocketPath !== undefined) {
+    try {
+      unlinkSync(opts.unixSocketPath);
+    } catch {}
+    await new Promise((resolve) => server.listen(opts.unixSocketPath, () => resolve()));
+  } else {
+    await new Promise((resolve) => server.listen(opts.port ?? 0, host, () => resolve()));
+  }
   const addr = server.address();
-  const port = addr && typeof addr === "object" ? addr.port : 0;
+  const port = addr && typeof addr === "object" && addr !== null ? addr.port : 0;
   return {
     host,
     port,
+    ...opts.unixSocketPath !== undefined ? { unixSocketPath: opts.unixSocketPath } : {},
     close: async () => {
       await new Promise((resolve) => server.close(() => resolve()));
       await Promise.all([...mitmServers.values()].map(({ server: s }) => new Promise((resolve) => s.close(() => resolve()))));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.154",
+  "version": "0.2.156",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:scripts": "tsc --project tsconfig.scripts.json --noEmit",
     "test": "bun test",
-    "test:core": "bun test src/cli src/core src/shell-source-audits.test.ts src/acp/ src/assets/ src/capability/ src/commands/ src/contracts/ src/ctx/ src/eval/ src/flow/ src/forgetting/ src/gdgraph/ src/gdskills/ src/health/ src/job/ src/lib/ src/mcp/ src/memory/ src/metrics/ src/retention/ src/review/ src/sac/ src/security/ src/standard/ src/sync/ src/testing/ src/trigger/ src/wiki/",
+    "test:core": "bun test src/cli src/core src/shell-source-audits.test.ts src/acp/ src/assets/ src/capability/ src/commands/ src/contracts/ src/ctx/ src/eval/ src/flow/ src/forgetting/ src/gdgraph/ src/gdskills/ src/governance/ src/health/ src/job/ src/lib/ src/mcp/ src/memory/ src/metrics/ src/retention/ src/review/ src/sac/ src/security/ src/standard/ src/sync/ src/testing/ src/trigger/ src/wiki/",
     "test:client:terminal": "bun test src/tui/ src/commands/shell",
     "test:client:streaming": "bun test src/harness/provider/",
     "test:client:cancel-resume": "bun test src/harness/run/ src/harness/resume/ src/harness/session/ src/session/ src/bus/ src/commands/sessions",

package/src/gdskills/bundled/rules/core/definition-of-done.mdc

@@ -93,7 +93,9 @@ not done either.
 When a frozen criterion genuinely conflicts with the bar — it asks for
 something that cannot be delivered without failing a clause — the criterion is
 not quietly reworded to match what was built. It changes through
-`keryx flow ac update <id> --reason "<why>"`, with the conflict as the reason,
+`keryx flow ac update <id> --reason "<why>"` (or `--criterion ACn --text
+"<criterion>" --reason "<why>"` to rewrite the line itself), with the conflict
+as the reason,
 per `.metaproject/skills/gdskills/orchestration/flow-orchestrator/SKILL.md`.
 Rewriting a criterion to describe the work is how a flow loses the only record
 of what it set out to do.

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -60,7 +60,7 @@ CLI-owned files:
 - task status - only through `keryx flow task done ...`.
 - task attempt counts - only through `keryx flow task attempt ...`.
 - frozen acceptance criteria changes - only through
-  `keryx flow ac update <id> --reason "<why>"`.
+  `keryx flow ac update <id> --reason "<why>"` (or `--criterion ACn --text "…"`; unused arguments are refused).
 
 Agent-editable files:
 
@@ -199,7 +199,7 @@ keryx flow init --issue <url>
 or:
 
 ```bash
-keryx flow init --title "<short formalized problem>" --base "<branch the work must land on>"
+keryx flow init --title "<short formalized problem>" --base "<branch the work must land on>" [--owner "<name>"]
 ```
 
 5. Run `keryx flow status <id>` and read the flow package.
@@ -631,7 +631,7 @@ keryx flow complete <id>
 
 Completion is allowed only after the PR merge has been confirmed. The merge
 target must be the base branch captured when the flow was created; do not
-silently retarget or close against another branch.
+silently retarget or close against another branch. Flows created since the owner gate fail completion while no owner is set (`keryx flow owner set <id> --owner "<name>" --reason "<why>"`); `ac confirm` and `flow complete` append a signature — `--signed-by "<name>"` names the signer, otherwise `KERYX_ACTOR` or the local git identity is recorded, as a claim. A flow created with `--require-confirmation` needs one more gate — `--confirm-token <token>` from `keryx flow confirm <id>`, a short-lived single-use token minted by a typed challenge in a terminal; it proves an interactive step ran outside the agent's tool roster, not that a human ran it. A flow left stuck in `completing` by a crash or interrupted attempt (never a normal gate failure) recovers with `keryx flow recover <id> --reason "<why>"`.
 
 If gates fail, the CLI returns the flow to `in-progress`. Add a journal note,
 create fix tasks, and repeat Phase 2.
@@ -688,7 +688,7 @@ Stop and re-read this skill if you are thinking:
 |---|---|
 | "The worker's reply reads like it finished, so the task is done." | The STATUS protocol says read the `STATUS:` line first and never infer the outcome from prose. A reply without one is `NEEDS_CONTEXT` — a confident-sounding summary is exactly what an unusable result looks like. |
 | "`DONE_WITH_CONCERNS` is still done, so I can move on." | Every concern goes into `journal.md` and gets an explicit continue-or-fix decision before `flow task done`. Concerns dropped at the task boundary are invisible by the completion report, which is where they would have mattered. |
-| "The acceptance criterion no longer matches what we built, so I'll reword it." | Frozen AC changes only through `keryx flow ac update <id> --reason "<why>"`. Rewriting a criterion to fit the implementation makes the flow pass a gate it actually failed, and leaves no record that it moved. |
+| "The acceptance criterion no longer matches what we built, so I'll reword it." | Frozen AC changes only through `keryx flow ac update <id> --reason "<why>"`, or `--criterion ACn --text "<criterion>" --reason "<why>"` to rewrite the line itself. Rewriting a criterion to fit the implementation makes the flow pass a gate it actually failed, and leaves no record that it moved. |
 | "`flow.json` is just a file — editing one field is faster than the CLI." | `flow.json`, status transitions, task status and attempt counts are CLI-owned. A hand-written field desynchronises the durable state from the flow's own history, and the CLI's next gate check reads yours, not reality. |
 | "Tests pass and the review is clean, so I'll open the PR and complete the flow." | Phase 4 stops and asks the user how the flow should end; not every flow wants a PR. And completion requires a confirmed merge into the base branch captured at creation — not a green local run. |
 | "The worker returned BLOCKED twice — faster if I implement this task myself." | The implementer never self-accepts and the orchestrator never implements. Block the flow, escalate one concise question, then unblock and re-dispatch. Doing the work here erases the boundary the whole flow model rests on. |

package/src/gdskills/bundled/skills/platform/scheduled-tasks/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: scheduled-tasks
+description: "Use when the operator asks for something to happen repeatedly in the background on a cadence (every 4 hours check my PRs, each morning summarise new issues) and a keryx schedule should be proposed with schedule_create. NOT for: one-off work done now (just do it), or git-event triggers declared in triggers.json (see hookify)."
+triggers:
+  - "schedule a task"
+  - "every 4 hours"
+  - "run in the background"
+  - "каждые 4 часа"
+  - "по расписанию"
+  - "check github regularly"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "platform"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+license: "MIT"
+---
+
+# Scheduled Tasks
+
+Turn "do this regularly" into a keryx schedule the OPERATOR confirms. keryx runs no
+daemon. After the operator's yes, it installs an OS timer (systemd --user, launchd or
+cron) that runs one unattended agent turn on the prompt and writes a report the
+operator reads in the shell's Schedules section.
+
+## Workflow
+
+### Step 1: Pin down the request
+- **Cadence**: cron, or a phrase keryx translates itself — `every N hours`
+  (a divisor of 24), `every N minutes` (5-30), `hourly`, `daily at HH:MM`,
+  `weekdays at HH:MM`, `every monday at HH:MM`. Never invent cron from a vague
+  "sometimes". Ask.
+- **Prompt**: the task in the operator's words, written for an agent that runs
+  alone and whose final message is the report.
+- **Budget**: `rates` (USD per million input/output tokens for the model) and
+  `ceilingUsd`. keryx has no price table. If you do not know the rates, ASK.
+  Never guess them.
+
+### Step 2: Grant only what the task needs
+- `tools`: pick from the fixed catalogue: `gh.pr.list`, `gh.pr.view`,
+  `gh.pr.checks`, `gh.issue.list`, `gh.issue.view`, `gh.run.list`. keryx
+  runs them OUTSIDE the sandbox with the operator's credentials, and the
+  scheduled agent sees only redacted output. A version-manager shim is refused. A `#!`
+  wrapper is pinned together with its interpreter, but its own global config
+  (its own config directory) stays outside what keryx pins.
+- `repos`: every repository those tools may touch (`owner/name`).
+- `network`: leave it `off`. Checking GitHub needs no sandbox network — the granted
+  tools cover it. `full` hands the shell the whole host network; say why. `allowlist`
+  (Linux only, `domains` required) reaches only the named domains, and governs only
+  the agent's own shell — never the model call or a granted tool.
+- `permissionMode`: `ask` (the default) is read-only, and granted tools still run.
+  Propose `trust` only when the scheduled agent must run shell commands.
+
+### Step 3: Propose with schedule_create
+Call `schedule_create`. The operator then sees a confirmation card: cadence and
+next runs, prompt, runner, budget, network, every granted tool with its binary
+and account, and exactly what gets installed. You do not confirm it. Only the
+operator can, and every permission mode asks, `auto` included.
+
+### Step 4: Report back
+After the operator's answer, say what was scheduled and when it next runs, or
+that nothing was written. Point to `/schedules` for the list and the reports.
+
+## Rules
+
+- NEVER try to confirm, retry past a "no", or re-propose the same schedule unchanged after it was declined.
+- NEVER create or install a schedule by any other route (editing
+  `.metaproject/data/trigger/schedules.json`, `keryx schedule add --yes` in your
+  shell, `systemctl`, `crontab`, `launchctl`). Each of these asks the operator.
+  `keryx schedule add` refuses inside your shell, and a hand-written entry lacks
+  this machine's signature, so it never runs.
+- NEVER read or copy the schedule signing key (`schedule-hmac.key`), and never try to
+  reach the scheduler another way (quoting, `env -u`, a script). The text floor can be
+  worked around, and that is exactly why it is not the gate. `keryx schedule add|resume|run`
+  need the operator's own terminal, and a schedule without this machine's signature never runs.
+- NEVER run `loginctl enable-linger`. If linger is off, tell the operator the
+  timer runs only while they are logged in and that the command is theirs to run.
+- State the limits when they matter: the machine must be on; systemd and launchd
+  catch up one missed run after sleep and cron none; `allowlist` is Linux only.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The operator said 'every so often' — I'll pick hourly" | A cadence runs and spends unattended. Ask for it |
+| "I'll grant every gh tool so the agent is not stuck" | Grants are the operator's credentials acting unattended. Grant what the prompt needs |
+| "Network full is simpler than granted tools" | It gives the unattended shell the whole host network. Granted tools need none |
+| "I know roughly what the model costs" | A wrong rate makes both spend ceilings wrong by the same factor. Ask |
+
+## Verification
+
+Do not report the schedule as created until all of the following hold:
+
+- `schedule_create` returned "stored and installed", not "not confirmed" or an error
+- `schedule_list` shows the entry, enabled, with the next run you told the operator
+- The grants you proposed are the ones the card showed, with nothing added afterwards