@bluewombat/slots 0.7.0 → 0.8.0

package/README.md

@@ -95,7 +95,13 @@ or `--report`. A role slot after `--` is what names one:
 `cursor.mjs` needs `cursor-agent` on PATH. Without `--agent-home` it uses the
 CLI's own login (`cursor-agent login`). With `--agent-home DIR` and
 `--api-key-env NAME` the vendor process gets that directory as `HOME` and
-`CURSOR_API_KEY` from `NAME`; the value never appears on the argv. `claude.mjs`
+`CURSOR_API_KEY` from `NAME`; the value never appears on the argv. It also gets
+a short environment (`PATH`, locale, proxy and certificate variables and a few
+others, plus the names given with `--pass-env`), not the operator's whole
+shell; git's credential helpers are cleared for it; and `ssh`, `scp` plus the
+commands given with `--deny-shell` are denied in its own `cli-config.json`,
+rewritten every run. That
+lowers a risk and confines nothing (RESERVATIONS F32). `claude.mjs`
 needs `claude`, signed in once, and refuses those two flags: Claude is not
 isolated yet, and starting it would keep the operator's own config.
 
@@ -112,6 +118,8 @@ isolated yet, and starting it would keep the operator's own config.
 | `--agent-arg VALUE`                | Appended to the CLI argv, before the prompt. Repeatable                          |
 | `--agent-home DIR`                 | Isolate the vendor process: its `HOME` is this directory. Cursor only; Claude refuses |
 | `--api-key-env NAME`               | With `--agent-home`, read `process.env[NAME]` for the vendor key. Never the value itself |
+| `--pass-env NAME`                  | With `--agent-home`, also hand the vendor this environment variable. Repeatable |
+| `--deny-shell NAME`                | With `--agent-home`, also refuse this command to the vendor (`gh`, `vercel`…). `ssh` and `scp` always are. Repeatable |
 | `--plugin-dir DIR`                 | A plugin folder of the operator's (a Mason home's `ai-plugins/core/*`). Repeatable, loaded first |
 | `--profile NAME`                   | The project's deck profile for this role, read in the working directory. Cursor only; Claude refuses |
 | `--plugins-out DIR`                | Where `--profile` is built, one folder per profile. Required with `--profile`; never the workspace |
@@ -239,14 +247,32 @@ assembly, so `assembly/fix` does not fill it at all.
 
 | Role                | Required                              | Also fills                                                 |
 | ------------------- | ------------------------------------- | ---------------------------------------------------------- |
-| `builders/producer` | `{{task}}`, `{{rules}}`               | `{{done_when}}`, `{{id}}`, `{{attempt}}`                   |
-| `builders/repair`   | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}` |
-| `assembly/fix`      | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{id}}`, `{{attempt}}`                  |
+| `builders/producer` | `{{task}}`, `{{rules}}`               | `{{history}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}`    |
+| `builders/repair`   | `{{task}}`, `{{report}}`, `{{rules}}` | `{{history}}`, `{{refused_by}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}` |
+| `assembly/fix`      | `{{task}}`, `{{report}}`, `{{rules}}` | `{{history}}`, `{{refused_by}}`, `{{id}}`, `{{attempt}}`   |
 | `assembly/validate` | `{{task}}`, `{{rules}}`               | `{{id}}`, `{{attempt}}`                                    |
 
 A first-pass command that receives `--report` is `fail-blocking`: that report
 belongs to the repair command. A repair or fix command without `--report` is the same.
 
+`{{history}}` is what the Task went through before this Attempt, oldest first (the
+refusal it came with, each Attempt, each Gate's answer; see Implementer's SPECS §
+History). It is empty on a first Attempt and vanishes whole then, so a template
+that does not place it works as before.
+
+### The way out
+
+Every shipped producer prompt ends with the same exit: when what the agent was
+given is not enough to act on, it changes nothing and ends its final message with
+one line, `MASON_BLOCKED: <what is missing>`. The slot reads the last such line
+in the agent's final message, and answers `fail-blocking` with that reason, so the
+Task stops as `escalated` and a person reads it instead of another Attempt
+inventing a change. This is the same kind of signal as `assembly/validate`'s
+`MASON_VERDICT:` line, and it is not tied to any refuser. A clean exit prints
+`{ "said": "<the agent's final message, clipped>" }` on stdout, which the Task
+keeps for its History. A Project's own template should keep a paragraph that
+tells the agent about the line, or the agent has no way to use it.
+
 ### The repair prompt
 
 A pass a Gate refused is a different job from a first pass: not "do this" but
@@ -420,7 +446,7 @@ the work in front of the checks did that before the Gate ran; a workspace
 with nothing published is `fail-blocking`, because no Attempt of that Task
 can change it.
 
-It waits while checks are running, so give it a ceiling of its own. On a red
+It waits while checks are running, so give it a ceiling of its own (the Gate's `timeoutMs`, which Implementer passes to it as `--timeout-ms`). A CI that does not answer is not a refusal of the work: a Gate killed by its clock reads as one, and a refusal sends the work to a producer with nothing to fix. So a few seconds before the ceiling, with no check yet or checks still running, `ci-green` answers `fail-blocking` itself, saying what it was waiting for and for how long, and a person reads it. A check that failed still refuses at once, with its reason. On a red
 check the report carries the failing job's log, cut at the error the runner
 marked — a check name and the word "failure" tell the next Attempt nothing it
 can act on. Right after a push the checks may not be created yet, and an empty

package/agents/cursor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import {
   AGENT_OPTIONS,
   findExecutable,
@@ -30,6 +30,12 @@ import { extrasFromCursor } from "./cursor-extras.mjs";
 //   --agent-home DIR      isolate this process: HOME is DIR, not the operator's
 //   --api-key-env NAME    required with --agent-home. Read process.env[NAME];
 //                         the value is never put on the argv
+//   --pass-env NAME       with --agent-home: also hand the vendor this variable
+//                         of the operator. Repeatable. The vendor otherwise
+//                         gets a short list (KEPT_ENV), not the whole environment
+//   --deny-shell NAME     with --agent-home: also refuse this command to the
+//                         vendor (`gh`, `vercel`…). Repeatable. ssh and scp are
+//                         always refused
 //   --plugin-dir / --profile / --plugins-out / --deck-bin   plugin folders,
 //                         see agent-plugins.mjs
 //   --id / --attempt / --context   how a transcript is filed
@@ -38,6 +44,45 @@ const NAME = "Cursor CLI";
 const CLI_NAMES = ["cursor-agent", "agent"];
 const INSTALL_DIRS = [join(homedir(), ".local/bin"), join(homedir(), ".cursor/bin")];
 
+/**
+ * What the vendor gets of the operator's environment, besides what this file
+ * sets itself: enough to find tools, name the locale and reach the network.
+ * Tokens, agent sockets and the rest of an interactive shell stay with the
+ * operator; a Project that needs one more names it with `--pass-env`.
+ */
+const KEPT_ENV = [
+  "PATH",
+  "TERM",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "TMPDIR",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "PNPM_HOME",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "NODE_EXTRA_CA_CERTS",
+];
+
+/**
+ * Commands refused to the vendor whatever the Project says: the ones that
+ * reach for the operator's own logins through a socket or a key. A Project adds
+ * its own with `--deny-shell` (the GitHub CLI reads a keychain whatever HOME
+ * is; `security` is macOS only; each machine has its own). The vendor's
+ * permission list refuses a command even under `--force`. It is a list of
+ * names, not a sandbox: `python -c` goes round it.
+ */
+const DENIED_SHELL = ["ssh", "scp"];
+
 const cwd = process.cwd();
 
 const parsed = parseOptions(process.argv.slice(2), AGENT_OPTIONS, NAME);
@@ -142,42 +187,93 @@ function cursorIsolation(options, dir) {
       reason: `The environment variable ${keyEnv} is empty. An isolated Cursor agent needs it, or the CLI tries to store credentials in the login keychain.`,
     };
   }
-  return { ok: true, env: isolatedVendorEnv(resolve(dir, home), apiKey) };
+  const passEnv = listOption(options, "passEnv");
+  const bad = passEnv.find((name) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name));
+  if (bad !== undefined) {
+    return { ok: false, reason: `--pass-env must name an environment variable, not "${bad}".` };
+  }
+  const denyShell = listOption(options, "denyShell");
+  const badCommand = denyShell.find((name) => !/^[A-Za-z0-9._+-]+$/.test(name));
+  if (badCommand !== undefined) {
+    return {
+      ok: false,
+      reason: `--deny-shell must name a command, not "${badCommand}".`,
+    };
+  }
+  const agentHome = resolve(dir, home);
+  const env = isolatedVendorEnv(agentHome, apiKey, passEnv);
+  denyShellCommands(agentHome, denyShell);
+  return { ok: true, env };
 }
 
 /**
  * @param {string} agentHome
  * @param {string} apiKey
+ * @param {readonly string[]} passEnv
  * @returns {NodeJS.ProcessEnv}
  */
-function isolatedVendorEnv(agentHome, apiKey) {
+function isolatedVendorEnv(agentHome, apiKey, passEnv) {
   mkdirSync(agentHome, { recursive: true });
   const parentHome = homedir();
   /** @type {NodeJS.ProcessEnv} */
-  const env = { ...process.env, HOME: agentHome };
-  if (process.env.PATH !== undefined) {
-    env.PATH = process.env.PATH;
+  const env = { HOME: agentHome };
+  for (const name of [...KEPT_ENV, ...passEnv]) {
+    if (process.env[name] !== undefined) {
+      env[name] = process.env[name];
+    }
   }
   env.CURSOR_API_KEY = apiKey;
   env.AGENT_CLI_CREDENTIAL_STORE = "memory";
+  // The operator's git config may name a credential helper (a keychain with
+  // their account). An empty helper first clears that list for the vendor's
+  // git, and a missing credential fails instead of prompting.
+  env.GIT_CONFIG_COUNT = "1";
+  env.GIT_CONFIG_KEY_0 = "credential.helper";
+  env.GIT_CONFIG_VALUE_0 = "";
+  env.GIT_TERMINAL_PROMPT = "0";
   const gitConfig = parentGitConfig(parentHome);
-  if (gitConfig === undefined) {
-    delete env.GIT_CONFIG_GLOBAL;
-  } else {
+  if (gitConfig !== undefined) {
     env.GIT_CONFIG_GLOBAL = gitConfig;
   }
   const npmCache = process.env.npm_config_cache;
   env.npm_config_cache =
     npmCache !== undefined && npmCache.length > 0 ? npmCache : join(parentHome, ".npm");
   const corepack = parentCorepack(parentHome);
-  if (corepack === undefined) {
-    delete env.COREPACK_HOME;
-  } else {
+  if (corepack !== undefined) {
     env.COREPACK_HOME = corepack;
   }
   return env;
 }
 
+/**
+ * Write the denials into the vendor's own config in `agentHome`, keeping what
+ * else is in it. Every pass, because the vendor can edit that file.
+ *
+ * @param {string} agentHome
+ * @param {readonly string[]} extra  commands the Project also refuses
+ */
+function denyShellCommands(agentHome, extra) {
+  const file = join(agentHome, ".cursor", "cli-config.json");
+  /** @type {Record<string, any>} */
+  let config = {};
+  try {
+    config = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    // none yet, or unreadable: start from nothing rather than refuse to run
+  }
+  const permissions = config.permissions ?? {};
+  const deny = Array.isArray(permissions.deny) ? permissions.deny : [];
+  config.permissions = {
+    ...permissions,
+    allow: Array.isArray(permissions.allow) ? permissions.allow : [],
+    deny: [...new Set([...deny, ...[...DENIED_SHELL, ...extra].map((name) => `Shell(${name})`)])],
+  };
+  mkdirSync(dirname(file), { recursive: true });
+  const next = `${file}.${process.pid}.tmp`;
+  writeFileSync(next, `${JSON.stringify(config, null, 2)}\n`);
+  renameSync(next, file);
+}
+
 /**
  * The global git file the parent already resolves. `~/.gitconfig` wins over
  * the XDG file, which is git's own order when both exist.

package/assembly/fix.mjs

@@ -40,6 +40,19 @@ This was asked in the first place, and still holds:
 
 {{task}}
 
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
 ## Rules of this run
 
 {{rules}}
@@ -79,6 +92,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     report,
     refused_by:
       refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",

package/builders/producer.mjs

@@ -28,6 +28,19 @@ This checkout already includes any earlier subtasks that were folded into the
 feature. Do not rewrite that work. Add or change only what this task names, and
 leave the project's own checks green on the whole tree.
 
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
 Rules of this run:
 {{rules}}
 `;
@@ -68,6 +81,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     done_when: doneWhen(take(process.argv, "--definition-of-done")),
     rules: rules.value.trim(),
     id: take(process.argv, "--id") ?? "",

package/builders/repair.mjs

@@ -40,6 +40,19 @@ This was asked in the first place, and still holds:
 
 {{done_when}}
 
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
 ## Rules of this run
 
 {{rules}}
@@ -79,6 +92,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     report,
     refused_by:
       refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",

package/gates/ci-green.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { emitVerdict, GATE_FLAGS, ownArgv } from "@bluewombat/slot-kit";
+import { emitVerdict, GATE_FLAGS, ownArgv, take } from "@bluewombat/slot-kit";
 
 // The work line's own checks, on the work this workspace published: GitHub
 // Actions' check runs, and the commit statuses CI outside Actions reports
@@ -20,6 +20,12 @@ import { emitVerdict, GATE_FLAGS, ownArgv } from "@bluewombat/slot-kit";
 //                        to it failed only at the first assembly of a real run
 //   --require-checks     wait for a check to appear; without it, a commit with no
 //                        check at all passes
+//
+// It also receives `--timeout-ms` from Implementer: the ceiling it will be
+// killed at. A Gate that waits on a CI it does not run must not wait to be cut
+// off: a kill reads as "refused", and a refusal sends the work to an agent that
+// has nothing to fix. Near that ceiling it says so itself, `fail-blocking`, with
+// what it was waiting for.
 
 // What the runner writes at the top of every step it runs.
 const STEP_OPEN = "##[group]Run ";
@@ -63,8 +69,10 @@ if (pull === undefined) {
   process.exit(0);
 }
 
-// Ask again until the answer settles. The ceiling is this Gate's own timeout:
-// reaching it ends the Attempt, and the next one asks from scratch.
+// Ask again until the answer settles, or until just before Implementer would
+// kill this Gate (`--timeout-ms`); without that flag, until it does.
+const startedAt = Date.now();
+const stopAt = stopTime(startedAt, take(process.argv, "--timeout-ms"));
 for (;;) {
   const checks = await readChecks(pull.sha);
   if (checks === undefined) {
@@ -77,16 +85,61 @@ for (;;) {
   }
   if (checks.total === 0 && options.requireChecks) {
     // Just after a push there is a window where the checks are not created
-    // yet, and an empty list then says nothing. Ask again; the Gate's timeout
-    // is what ends the wait on a commit no check ever picks up.
-    await sleep(options.pollMs);
+    // yet, and an empty list then says nothing. Ask again, until the wait
+    // runs out: a commit no check ever picks up is not a refusal of the work.
+    if (Date.now() >= stopAt) {
+      stopWaiting(pull, "no check has appeared");
+    }
+    await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
     continue;
   }
   if (checks.running === 0) {
     emitVerdict("pass");
     process.exit(0);
   }
-  await sleep(options.pollMs);
+  if (Date.now() >= stopAt) {
+    stopWaiting(
+      pull,
+      `${checks.running} check${checks.running === 1 ? " was" : "s were"} still running`,
+    );
+  }
+  await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
+}
+
+/**
+ * The moment to stop waiting: a margin before Implementer's ceiling (5 %, between
+ * 2 and 30 seconds, and at most half of it), so the verdict is out before the
+ * kill. `Infinity` when Implementer gave no ceiling.
+ *
+ * @param {number} from
+ * @param {string | undefined} raw
+ */
+function stopTime(from, raw) {
+  const ceiling = Number.parseInt(raw ?? "", 10);
+  if (!Number.isInteger(ceiling) || ceiling <= 0) {
+    return Number.POSITIVE_INFINITY;
+  }
+  const margin = Math.min(Math.max(2_000, ceiling * 0.05), 30_000, ceiling / 2);
+  return from + ceiling - margin;
+}
+
+/**
+ * The CI did not answer. That says nothing of the work, and nothing the work
+ * could change: blocking, so a person reads it instead of an agent being sent
+ * to repair what was never judged.
+ *
+ * @param {{ number: number; sha: string }} pr
+ * @param {string} what
+ * @returns {never}
+ */
+function stopWaiting(pr, what) {
+  const seconds = Math.round((Date.now() - startedAt) / 1000);
+  const lasted = seconds >= 120 ? `${Math.round(seconds / 60)} min` : `${seconds} s`;
+  emitVerdict(
+    "fail-blocking",
+    `ci-green stopped waiting after ${lasted}: ${what} on ${pr.sha.slice(0, 7)} (pull request #${pr.number}). The CI did not answer in time; this is not a refusal of the work, and no change to it can make the CI answer.`,
+  );
+  process.exit(0);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Shipped mason slots: Planners, Builders, Gates, publishers, and refreshers a Project names in its config.",
   "keywords": [
@@ -53,7 +53,7 @@
     "test": "tsx --test $(find test -name '*.test.ts')"
   },
   "dependencies": {
-    "@bluewombat/slot-kit": "^0.7.0",
+    "@bluewombat/slot-kit": "^0.8.0",
     "@pinkpuma/deck": "1.0.0"
   }
 }