loopctl-mcp-server 2.91.0 → 2.92.0

package/README.md

@@ -70,7 +70,7 @@ Or if installed locally:
 | `LOOPCTL_API_KEY` | Global API key override (if set, always used) | -- |
 | `LOOPCTL_ORCH_KEY` | Orchestrator role API key (verify, reject, review, import) | -- |
 | `LOOPCTL_AGENT_KEY` | Agent role API key (contract, claim, start, request-review) | -- |
-| `LOOPCTL_USER_KEY` | User role API key (minted at signup). Required for **first-time BYO LLM key provisioning** (`set_llm_config` / `llm_config` — see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)) and for destructive admin tools like `knowledge_bulk_publish`. | -- |
+| `LOOPCTL_USER_KEY` | User role API key (minted at signup). Required for **first-time BYO LLM key provisioning** (`set_llm_config` / `llm_config` — see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)) and for destructive admin tools like `knowledge_bulk_publish`, and for the [runner tools](#runner-tools-user-key). | -- |
 | `LOOPCTL_STH_STATE_PATH` | Absolute path for the witness-protocol STH cache file (see [Witness protocol](#witness-protocol-sth)). Optional. | per-(server + key) file under the OS temp dir |
 
 Key resolution priority: `LOOPCTL_API_KEY` > tool-specific key > `LOOPCTL_ORCH_KEY`.
@@ -218,7 +218,8 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | Tool | Description |
 |---|---|
 | `contract_story` | Agent acknowledges a story's acceptance criteria. Transitions pending -> contracted. |
-| `claim_story` | Agent claims a contracted story with pessimistic locking. Transitions contracted -> assigned. |
+| `claim_story` | Agent claims a contracted story with pessimistic locking. Transitions contracted -> assigned. On a loopctl with claim leases the result leads with the claim's `claim_epoch` and `claimed_until`; keep the epoch for `renew_story_claim`. Both are absent on an older server. |
+| `renew_story_claim` | Renew your claim's lease (`POST /stories/:id/renew-claim`, agent key). A claim not renewed before `claimed_until` (default 24 hours, `STORY_CLAIM_LEASE_SECONDS`) is released back to `pending` under you, so renew well inside it on any story held longer. Required: `story_id`, `claim_epoch` (from the claim). Refusals pass through: 400 epoch missing or malformed, 422 `not_claimed`, 409 `stale_claim_epoch` (the claim has ended: stop working it), 409 `not_claimant`. Needs a loopctl server with claim leases. |
 | `start_story` | Agent starts work on a claimed story. Transitions assigned -> implementing. |
 | `request_review` | Agent signals implementation is complete and ready for review. |
 
@@ -464,6 +465,17 @@ through the same authenticated + witness/STH path as every static read tool. If
 `/retrieve/tools` fetch fails, listing degrades to the static tools (never errors).
 The generated-tool count per tenant is bounded by the per-tenant entity cap.
 
+### Runner Tools (user key)
+
+Enroll the dev machines that run the agent delivery loop, and see which are connected (issue #809). All four require `LOOPCTL_USER_KEY`; enroll and revoke also require a human-anchored tenant.
+
+| Tool | Description |
+|---|---|
+| `runner_enroll` | Enroll this machine as a runner (`POST /api/v1/runners`). Required: `name` (the machine name the runner declares when it joins) and `token_file` (absolute, or starting with `~/`). The credential is written to `token_file` with mode 0600 and is **never returned**: the result is only `{ runner: {id, name, inserted_at}, token_file }`, because a tool result lands in the transcript and the token lets its holder join as that machine. The file is created exclusively, so an existing path (or a symlink there) is refused before anything is enrolled; missing parent directories are created 0700. If the token cannot be written after enrollment, the runner is revoked before the error returns. Only a 4xx is treated as a refusal: any other failure (timeout, 5xx, a 2xx that did not parse) may have enrolled the runner, so its response body is never echoed, the runner is revoked when the response proves its id, and otherwise the error points at `runner_list` and `runner_revoke`. 422 (name malformed or taken) and 403 (`custody_tier_required`, `api_key_mint_forbidden`) pass through with their code. |
+| `runner_list` | List enrolled runners (`GET /api/v1/runners`). Optional: `include_revoked`. Enrollment only; connection state is `runner_pool`. |
+| `runner_revoke` | Revoke a runner (`DELETE /api/v1/runners/:id`): its credential stops authenticating and its live socket is disconnected. The undo for `runner_enroll`. Idempotent. Required: `id`. |
+| `runner_pool` | The tenant's connected runners from Presence (`GET /api/v1/runners/pool`): per machine name, `runner_id`, `joined_at`, `in_flight`, `draining`, `max_sessions`, the latest `sample`, and `live_sockets` (above 1 means more than one process holds the credential). Presence converges only within a cluster. |
+
 ### Dispatch & Chain of Custody (v2) Tools
 
 Key distribution for the dispatch pattern (Epic 26): per-dispatch ephemeral keys and capability-token recovery. See `docs/chain-of-custody-v2.md`.

package/index.js

@@ -43,6 +43,9 @@ import {
   GENERATED_TOOL_PREFIX,
 } from "./lib/generated-tools.js";
 import { createHandoff } from "./lib/handoff.js";
+import { readPayloadFile } from "./lib/payload-path.js";
+import { enrollRunner, listRunners, revokeRunner, runnerPool } from "./lib/runners.js";
+import { claimLeaseNotice, renewStoryClaim as renewStoryClaimRequest } from "./lib/claim-lease.js";
 
 // Single source of truth for the server version: the package.json this file
 // ships with (npm always includes package.json in the published tarball).
@@ -967,13 +970,7 @@ async function importStories({ project_id, payload, payload_path, merge }) {
 
 // Reads JSON payload from either an inline object or an absolute file path.
 // Returns the object on success, or an { error, body } shape on failure.
-//
-// Security: `payload_path` is read with the MCP process's filesystem
-// privileges. Because agents can set this argument via prompt injection,
-// we validate aggressively:
-//   * require absolute path
-//   * reject /proc, /dev, /sys (pseudo-filesystems that could DoS or leak)
-//   * stat first and cap at 5 MiB (server also enforces a body size limit)
+// The file path is validated in lib/payload-path.js (see its security notes).
 async function resolvePayload(inline, payloadPath) {
   if (inline && typeof inline === "object") return inline;
   if (!payloadPath) {
@@ -983,53 +980,7 @@ async function resolvePayload(inline, payloadPath) {
       body: "Must provide either `payload` (object) or `payload_path` (absolute JSON file path).",
     };
   }
-
-  const nodePath = await import("node:path");
-  if (!nodePath.isAbsolute(payloadPath)) {
-    return {
-      error: true,
-      status: 0,
-      body: `payload_path must be absolute (got '${payloadPath}').`,
-    };
-  }
-
-  const blockedPrefixes = ["/proc/", "/dev/", "/sys/", "/proc", "/dev", "/sys"];
-  if (blockedPrefixes.some((p) => payloadPath === p.replace(/\/$/, "") || payloadPath.startsWith(p))) {
-    return {
-      error: true,
-      status: 0,
-      body: `payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`,
-    };
-  }
-
-  const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
-  const fs = await import("node:fs/promises");
-
-  try {
-    const stat = await fs.stat(payloadPath);
-    if (!stat.isFile()) {
-      return {
-        error: true,
-        status: 0,
-        body: `payload_path '${payloadPath}' is not a regular file.`,
-      };
-    }
-    if (stat.size > MAX_PAYLOAD_BYTES) {
-      return {
-        error: true,
-        status: 0,
-        body: `payload_path '${payloadPath}' is ${stat.size} bytes, exceeds max ${MAX_PAYLOAD_BYTES}.`,
-      };
-    }
-    const raw = await fs.readFile(payloadPath, "utf8");
-    return JSON.parse(raw);
-  } catch (err) {
-    return {
-      error: true,
-      status: 0,
-      body: `Could not read payload_path '${payloadPath}': ${err.message}`,
-    };
-  }
+  return readPayloadFile(payloadPath);
 }
 
 // --- Story Tools ---
@@ -1185,7 +1136,19 @@ async function claimStory({ story_id }) {
   );
   // The claim response carries the start_cap that POST /start will require.
   rememberCap(story_id, result && result.capability);
-  return toContent(result);
+  return withClaimLeaseNotice(result);
+}
+
+// #803/#810: a claim carries a lease and an epoch. Put both at the top of the result, when
+// the server returns them, so the agent keeps the epoch renew_story_claim needs.
+function withClaimLeaseNotice(result) {
+  const notice = claimLeaseNotice(result);
+  if (!notice) return toContent(result);
+  return { content: [{ type: "text", text: notice }, ...toContent(result).content] };
+}
+
+async function renewStoryClaim(args) {
+  return withClaimLeaseNotice(await renewStoryClaimRequest(args, { apiCall }));
 }
 
 async function startStory({ story_id, capability }) {
@@ -3148,6 +3111,34 @@ async function revokeAuthenticator({ tenant_id, authenticator_id, webauthn_asser
   return toContent(result);
 }
 
+// Issue #809: runner tools. All four take the EXACT user-role key: a runner credential
+// is minted by a user key on a human-anchored tenant, and a global LOOPCTL_API_KEY must
+// never stand in for it. The logic, including how runner_enroll keeps the token out of
+// the tool result, lives in lib/runners.js.
+function runnerDeps() {
+  const userKey = process.env.LOOPCTL_USER_KEY;
+  return {
+    userKey,
+    apiCall: (method, path, body) => apiCall(method, path, body, userKey, { exactKey: true }),
+  };
+}
+
+async function runnerEnroll(args) {
+  return toContent(await enrollRunner(args, runnerDeps()));
+}
+
+async function runnerList(args) {
+  return toContent(await listRunners(args, runnerDeps()));
+}
+
+async function runnerRevoke(args) {
+  return toContent(await revokeRunner(args, runnerDeps()));
+}
+
+async function runnerPoolRead(args) {
+  return toContent(await runnerPool(args, runnerDeps()));
+}
+
 // US-26: Signed Tree Head retrieval
 async function getSth({ tenant_id }) {
   const result = await apiCall("GET", `/api/v1/audit/sth/${tenant_id}`);
@@ -3927,7 +3918,7 @@ const TOOLS = [
         payload_path: {
           type: "string",
           description:
-            "Absolute path to a JSON file with the import payload. Avoids inline size limits for large epics. Ignored if `payload` is also passed.",
+            "Absolute path to a .json file holding the import payload (an object with an `epics` array). Avoids inline size limits for large epics. Ignored if `payload` is also passed.",
         },
         merge: {
           type: "boolean",
@@ -4053,7 +4044,10 @@ const TOOLS = [
     name: "claim_story",
     description:
       "Agent claims a contracted story. Uses pessimistic locking to prevent double-claims. " +
-      "Transitions contracted -> assigned. Uses the AGENT key.",
+      "Transitions contracted -> assigned. Uses the AGENT key. On a loopctl with claim leases " +
+      "the result leads with the claim's claim_epoch and claimed_until: keep the epoch, and " +
+      "renew with renew_story_claim before claimed_until (default lease 24 hours) or the story " +
+      "is released back to pending under you.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4065,6 +4059,32 @@ const TOOLS = [
       required: ["story_id"],
     },
   },
+  {
+    name: "renew_story_claim",
+    description:
+      "Renew your claim's lease (POST /api/v1/stories/:id/renew-claim): claimed_until becomes " +
+      "now plus the lease length, measured from NOW. Call it well inside the lease on any story " +
+      "you hold longer than it. Uses the AGENT key, the same key as claim_story. Refusals pass " +
+      "through: 400 claim_epoch missing or not a non-negative integer; 422 not_claimed (the " +
+      "story is not assigned or implementing); 409 stale_claim_epoch (the claim has ENDED: it " +
+      "expired and was reclaimed, released, or claimed again, so stop working it); 409 " +
+      "not_claimant (your key's agent is not the story's assigned agent).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        story_id: {
+          type: "string",
+          description: "The UUID of the story.",
+        },
+        claim_epoch: {
+          type: "integer",
+          minimum: 0,
+          description: "The claim_epoch your claim_story result returned.",
+        },
+      },
+      required: ["story_id", "claim_epoch"],
+    },
+  },
   {
     name: "start_story",
     description:
@@ -7443,6 +7463,81 @@ const TOOLS = [
     },
   },
 
+  // Issue #809: runner enrollment and the Presence pool (user key)
+  {
+    name: "runner_enroll",
+    description:
+      "Enroll this dev machine as a runner of the agent delivery loop (POST /api/v1/runners). " +
+      "The runner's credential is written to `token_file` with mode 0600 and is NEVER returned: " +
+      "whoever holds it can join as this machine and receive its dispatches, and a tool result " +
+      "lands in the transcript. The result is only `{ runner: {id, name, inserted_at}, token_file }`. " +
+      "The file is created exclusively (O_EXCL): an existing path is refused before anything is " +
+      "enrolled, never overwritten. Missing parent directories are created with mode 0700. If the " +
+      "token cannot be written after enrollment, the runner is revoked before the error returns. " +
+      "A failure that may still have enrolled it (timeout, 5xx, a 2xx that did not parse) never " +
+      "echoes the response body: the runner is revoked when the response proves its id, and " +
+      "otherwise the error says to find it with runner_list and revoke it. " +
+      "runner_revoke is the undo for an enrollment. Requires LOOPCTL_USER_KEY (user role) on a " +
+      "human-anchored tenant; errors pass through with their code (422 name malformed or taken, " +
+      "403 custody_tier_required or api_key_mint_forbidden).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "The machine name the runner will declare when it joins, e.g. `minis`.",
+        },
+        token_file: {
+          type: "string",
+          description:
+            "Absolute path, or one starting with ~/, for the token file. Must not exist yet.",
+        },
+      },
+      required: ["name", "token_file"],
+    },
+  },
+  {
+    name: "runner_list",
+    description:
+      "List the tenant's enrolled runners (GET /api/v1/runners): id, name, revoked_at, inserted_at. " +
+      "Enrollment only, never tokens; whether a runner is CONNECTED is runner_pool. " +
+      "Requires LOOPCTL_USER_KEY (user role).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        include_revoked: {
+          type: "boolean",
+          description: "Include revoked runners. Default false.",
+        },
+      },
+    },
+  },
+  {
+    name: "runner_revoke",
+    description:
+      "Revoke a runner (DELETE /api/v1/runners/:id): its credential stops authenticating and its " +
+      "live socket is disconnected, which removes it from runner_pool. This is the undo for " +
+      "runner_enroll. Idempotent. Requires LOOPCTL_USER_KEY (user role) on a human-anchored tenant.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The runner UUID (from runner_enroll or runner_list)." },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "runner_pool",
+    description:
+      "The tenant's CONNECTED runners, read from Presence (GET /api/v1/runners/pool): per machine " +
+      "name, runner_id, joined_at, in_flight, draining, max_sessions, the latest health sample, " +
+      "and live_sockets. live_sockets above 1 means more than one process holds that runner's " +
+      "credential. A killed runner disappears once its socket closes. Presence converges only " +
+      "within a cluster, so on an unclustered multi-node deployment a runner on another node is " +
+      "absent. Requires LOOPCTL_USER_KEY (user role).",
+    inputSchema: { type: "object", properties: {} },
+  },
+
   // LCP-1 §9 signed-profile tools
   {
     name: "register_custody_owner_key",
@@ -8181,6 +8276,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "claim_story":
       return await claimStory(args);
 
+    case "renew_story_claim":
+      return await renewStoryClaim(args);
+
     case "start_story":
       return await startStory(args);
 
@@ -8447,6 +8545,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "dispatch":
       return await createDispatch(args);
 
+    case "runner_enroll":
+      return await runnerEnroll(args);
+
+    case "runner_list":
+      return await runnerList(args);
+
+    case "runner_revoke":
+      return await runnerRevoke(args);
+
+    case "runner_pool":
+      return await runnerPoolRead(args);
+
     case "register_custody_owner_key":
       return await registerCustodyOwnerKey(args);
 

package/lib/claim-lease.js

@@ -0,0 +1,52 @@
+/**
+ * Story claim leases (loopctl #803/#810, MCP side under #809).
+ *
+ * A claim now carries a LEASE (`claimed_until`, default 24h, STORY_CLAIM_LEASE_SECONDS)
+ * and a FENCE (`claim_epoch`, bumped by every claim and every release). A claim that is not
+ * renewed before `claimed_until` is released back to `pending` under the agent still
+ * working it. `renew_story_claim` is the MCP path to `POST /stories/:id/renew-claim`, and
+ * `claimLeaseNotice` puts the epoch and the deadline at the top of a `claim_story` result so
+ * the agent keeps the epoch the renewal needs.
+ *
+ * SINGLE SOURCE OF TRUTH. index.js injects `apiCall`; the unit suite runs this code with a
+ * recording fake. The KEY is selected here, from the injected env, so the key a renewal
+ * travels on is testable behaviour rather than a source pattern.
+ *
+ * Nothing is validated client-side beyond `story_id`: the server's 400 (missing or
+ * non-integer epoch), 422 `not_claimed`, 409 `stale_claim_epoch` and 409 `not_claimant`
+ * pass through unchanged, because each one tells the agent something different to do.
+ */
+
+export function renewClaimPath(storyId) {
+  return `/api/v1/stories/${encodeURIComponent(storyId)}/renew-claim`;
+}
+
+/**
+ * `POST /api/v1/stories/:id/renew-claim {claim_epoch}` on the AGENT key, the same key
+ * `claim_story` uses. `claim_epoch` is forwarded exactly as given.
+ */
+export async function renewStoryClaim({ story_id, claim_epoch } = {}, { apiCall, env = process.env } = {}) {
+  if (typeof story_id !== "string" || story_id.trim() === "") {
+    return { error: true, status: 0, body: "`story_id` is required." };
+  }
+  return apiCall("POST", renewClaimPath(story_id), { claim_epoch }, env.LOOPCTL_AGENT_KEY);
+}
+
+/**
+ * A leading line for a claim or renewal result naming the claim's epoch and lease, or null
+ * when the server returned neither (an older loopctl, or an error).
+ */
+export function claimLeaseNotice(result) {
+  const story = result && result.error !== true ? result.story : null;
+  if (!story || !Number.isInteger(story.claim_epoch)) return null;
+
+  const lease = story.claimed_until
+    ? `claimed_until ${story.claimed_until}: renew with renew_story_claim before then, or the ` +
+      "story is released back to pending under you."
+    : "no lease (claimed_until is null), so it is never released automatically.";
+
+  return (
+    `CLAIM LEASE: claim_epoch ${story.claim_epoch}, ${lease} Keep claim_epoch; ` +
+    "renew_story_claim requires it. A 409 stale_claim_epoch means the claim has ended: stop working it."
+  );
+}

package/lib/payload-path.js

@@ -0,0 +1,96 @@
+// Reads an import_stories payload from an absolute file path.
+//
+// Security: `payload_path` is read with the MCP process's filesystem privileges and an
+// agent can set it via prompt injection, so no file CONTENT is ever returned, and a file
+// that is not an import payload is never uploaded. The refusals still say which check
+// failed (missing, not a file, too large, not JSON, wrong shape) for a .json path; that
+// is metadata an agent needs to fix its own call, not content:
+//   * require an absolute path ending in .json, checked on the path AND on its realpath,
+//     so a symlink named x.json cannot point at /etc/passwd or /proc
+//   * reject /proc, /dev, /sys (pseudo-filesystems that could DoS or leak)
+//   * stat first and cap at 5 MiB (server also enforces a body size limit)
+//   * never echo a JSON.parse or fs error message: V8's SyntaxError quotes the file's
+//     content ("root:x:0:0"... is not valid JSON), so only err.code is reported
+//   * require the Epic 12 import shape (an object with an `epics` array) before returning,
+//     so a valid JSON file that is not a payload (a credentials file) is never POSTed
+//
+// Returns the parsed payload on success, or an { error, status, body } shape on failure.
+
+import nodePath from "node:path";
+import defaultFs from "node:fs/promises";
+
+export const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+
+const BLOCKED_ROOTS = ["/proc", "/dev", "/sys"];
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+function isBlocked(p) {
+  return BLOCKED_ROOTS.some((root) => p === root || p.startsWith(root + "/"));
+}
+
+function hasJsonExtension(p) {
+  return nodePath.extname(p).toLowerCase() === ".json";
+}
+
+export async function readPayloadFile(payloadPath, { fs = defaultFs } = {}) {
+  if (typeof payloadPath !== "string" || !nodePath.isAbsolute(payloadPath)) {
+    return refuse(`payload_path must be absolute (got '${payloadPath}').`);
+  }
+
+  if (isBlocked(nodePath.resolve(payloadPath))) {
+    return refuse(`payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`);
+  }
+
+  if (!hasJsonExtension(payloadPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' must be a .json file.`);
+  }
+
+  let realPath;
+  try {
+    realPath = await fs.realpath(payloadPath);
+  } catch (err) {
+    return refuse(`Could not read payload_path '${payloadPath}' (${err.code || "error"}).`);
+  }
+
+  if (isBlocked(realPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`);
+  }
+
+  if (!hasJsonExtension(realPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' must be a .json file.`);
+  }
+
+  let raw;
+  try {
+    const stat = await fs.stat(realPath);
+    if (!stat.isFile()) {
+      return refuse(`payload_path '${payloadPath}' is not a regular file.`);
+    }
+    if (stat.size > MAX_PAYLOAD_BYTES) {
+      return refuse(
+        `payload_path '${payloadPath}' exceeds max ${MAX_PAYLOAD_BYTES} bytes.`,
+      );
+    }
+    raw = await fs.readFile(realPath, "utf8");
+  } catch (err) {
+    return refuse(`Could not read payload_path '${payloadPath}' (${err.code || "error"}).`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return refuse(`payload_path '${payloadPath}' is not valid JSON.`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Array.isArray(parsed.epics)) {
+    return refuse(
+      `payload_path '${payloadPath}' is not an import payload (expected an object with an "epics" array).`,
+    );
+  }
+
+  return parsed;
+}

package/lib/runners.js

@@ -0,0 +1,269 @@
+/**
+ * Runner tools (loopctl issue #809): enroll, list and revoke the runners of the agent
+ * delivery loop, and read the tenant's connected pool.
+ *
+ * WHY ENROLL WRITES A FILE. `POST /api/v1/runners` returns the runner's credential once.
+ * Whoever holds it can join as that machine and receive its dispatches. A tool result
+ * lands in the session transcript and the audit log, so the token must never be in one.
+ * This process runs on the machine being enrolled, so `enrollRunner` writes the token to
+ * `token_file` itself and returns only the runner row and the path.
+ *
+ * The file is RESERVED before the API is called: it is opened O_CREAT|O_EXCL with mode
+ * 0600, so an existing path (or a symlink at that path) is refused without enrolling
+ * anything, and a missing or unwritable directory fails before a credential exists. What
+ * can still fail after enrollment is the write itself (ENOSPC, EIO). That token is then
+ * unrecoverable, so the runner is revoked before the error is returned.
+ *
+ * Only a 4xx is an unambiguous refusal. Every other failure may have enrolled the runner,
+ * and a 2xx whose body failed to parse carries the token in the text apiCall kept, so on
+ * those paths no response body is echoed at all (`ambiguousEnrollment`).
+ *
+ * Missing PARENT directories are created with mode 0700. That is safe: `mkdir` with
+ * `recursive` leaves every existing directory's mode alone, only ever creates directories
+ * this user owns, and 0700 is no wider than the 0600 file inside. Refusing instead would
+ * make the first enrollment on a fresh machine fail on `~/.config/loopctl-runner/`.
+ *
+ * SINGLE SOURCE OF TRUTH. index.js calls these functions with the HTTP call injected, so
+ * the unit suite exercises the shipped code with fakes and a real temp directory.
+ *
+ * Nothing in this module logs. The token lives in one local variable and is only ever
+ * passed to the file handle's write.
+ */
+
+import nodePath from "node:path";
+import os from "node:os";
+import { constants as fsConstants } from "node:fs";
+import defaultFs from "node:fs/promises";
+
+export const TOKEN_FILE_MODE = 0o600;
+export const TOKEN_DIR_MODE = 0o700;
+export const TOKEN_FILE_FLAGS = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL;
+
+export const RUNNERS_PATH = "/api/v1/runners";
+export const RUNNER_POOL_PATH = "/api/v1/runners/pool";
+
+export function runnerPath(id) {
+  return `${RUNNERS_PATH}/${encodeURIComponent(id)}`;
+}
+
+const MISSING_USER_KEY =
+  "No user-role API key configured. Set LOOPCTL_USER_KEY to a user-role key to use the " +
+  "runner tools (runner_enroll, runner_list, runner_revoke, runner_pool).";
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+/**
+ * Expand a leading `~` (alone or followed by a separator) to `homedir`. `~user` forms are
+ * left as they are and then refused as relative.
+ */
+export function expandHome(p, homedir = os.homedir()) {
+  if (p === "~") return homedir;
+  if (p.startsWith("~/")) return nodePath.join(homedir, p.slice(2));
+  return p;
+}
+
+/**
+ * `POST /api/v1/runners {name}`, with the returned token written to `token_file` and
+ * never returned. Resolves to `{ runner: {id, name, inserted_at}, token_file }` or an
+ * `{ error: true, status, body }` shape. It never throws.
+ */
+export async function enrollRunner(
+  { name, token_file } = {},
+  { userKey, apiCall, fs = defaultFs, homedir = os.homedir() } = {},
+) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+  if (typeof name !== "string" || name.trim() === "") return refuse("`name` is required.");
+  if (typeof token_file !== "string" || token_file.trim() === "") {
+    return refuse("`token_file` is required: the path the runner's token is written to (mode 0600).");
+  }
+
+  const tokenPath = expandHome(token_file, homedir);
+  if (!nodePath.isAbsolute(tokenPath)) {
+    return refuse(`token_file must be absolute or start with ~/ (got '${token_file}').`);
+  }
+
+  let handle;
+  try {
+    await fs.mkdir(nodePath.dirname(tokenPath), { recursive: true, mode: TOKEN_DIR_MODE });
+    handle = await fs.open(tokenPath, TOKEN_FILE_FLAGS, TOKEN_FILE_MODE);
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      return refuse(
+        `token_file '${tokenPath}' already exists; refusing to overwrite it. Nothing was enrolled. ` +
+          "Choose a new path, or remove the file yourself if its runner is revoked.",
+      );
+    }
+    return refuse(
+      `Could not create token_file '${tokenPath}' (${err?.code || "error"}). Nothing was enrolled.`,
+    );
+  }
+
+  // The identity of the file this call created, taken BEFORE anything is written, so the
+  // file can still be told apart from a replacement if the handle later becomes unusable.
+  let opened;
+  try {
+    opened = await handle.stat();
+  } catch (err) {
+    await closeQuietly(handle);
+    return refuse(
+      `Could not stat the new token_file '${tokenPath}' (${err?.code || "error"}). Nothing was ` +
+        "enrolled; an empty file may remain at that path.",
+    );
+  }
+
+  let result;
+  try {
+    result = await apiCall("POST", RUNNERS_PATH, { name });
+  } catch {
+    result = { error: true, status: 0, body: "Enrollment request failed." };
+  }
+
+  // A 4xx is a refusal: nothing was committed, and its body is the server's error, which
+  // carries a code the caller needs. Pass it through as it came.
+  if (result && result.error === true && result.status >= 400 && result.status < 500) {
+    const removed = await discardReservation(fs, handle, tokenPath, opened);
+    return removed ? result : { ...result, token_file_not_removed: tokenPath };
+  }
+
+  const runner = result && result.error !== true ? result.runner : undefined;
+  const token = result && result.error !== true ? result.token : undefined;
+
+  if (!runner || typeof runner.id !== "string" || typeof token !== "string" || token === "") {
+    const removed = await discardReservation(fs, handle, tokenPath, opened);
+    return ambiguousEnrollment(result, runner, apiCall, tokenPath, removed);
+  }
+
+  try {
+    await handle.writeFile(token);
+    await handle.sync();
+    await handle.close();
+  } catch (err) {
+    const removed = await discardReservation(fs, handle, tokenPath, opened);
+    const revoked = await revoke(apiCall, runner.id);
+    return refuse(
+      `Runner '${runner.name}' (${runner.id}) was enrolled, but its token could not be written ` +
+        `to '${tokenPath}' (${err?.code || "error"}). The token cannot be relied on, so ` +
+        (revoked.ok
+          ? "the runner was revoked. "
+          : `revoking the runner FAILED (${revoked.detail}); revoke it with runner_revoke id ` +
+            `${runner.id}. `) +
+        reservationOutcome(tokenPath, removed),
+    );
+  }
+
+  return {
+    runner: { id: runner.id, name: runner.name, inserted_at: runner.inserted_at },
+    token_file: tokenPath,
+  };
+}
+
+// Every outcome that is neither a 4xx refusal nor a well-formed enrollment: a timeout, a
+// network error, a 5xx from the edge after the commit, a 3xx, or a 2xx whose body did not
+// parse or lacks the token. The runner MAY exist, so no response body is ever echoed — a
+// 2xx body that failed to parse is the enrollment itself, token included, and apiCall puts
+// its first 200 characters in `body`. The runner is revoked only when this response proves
+// its id; a runner found by name alone could be an earlier, legitimate enrollment.
+async function ambiguousEnrollment(result, runner, apiCall, tokenPath, removed) {
+  const status = result && Number.isInteger(result.status) ? result.status : undefined;
+  const id = (runner && typeof runner.id === "string" && runner.id) || provenRunnerId(result);
+
+  const what =
+    status === 0 && typeof result.body === "string"
+      ? `Enrollment outcome unknown (${result.body}).`
+      : `Enrollment outcome unknown (HTTP ${status ?? "?"}; response body withheld: it may contain the token).`;
+
+  let next;
+  if (id) {
+    const revoked = await revoke(apiCall, id);
+    next = revoked.ok
+      ? `The response identified runner ${id}; it was revoked, since its token cannot be recovered.`
+      : `The response identified runner ${id}, but revoking it FAILED (${revoked.detail}); revoke it with runner_revoke.`;
+  } else {
+    next =
+      "The runner may have been enrolled with a token nobody holds. Check runner_list for it " +
+      "(an active runner with this name and a new inserted_at) and revoke it with runner_revoke " +
+      "before enrolling again.";
+  }
+
+  return { error: true, status: status ?? 0, body: `${what} ${next} ${reservationOutcome(tokenPath, removed)}` };
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// The runner id from a 2xx response that did not parse. The id is read from the raw text
+// apiCall kept, is required to be a UUID inside the "runner" object, and never leaves this
+// function as anything but that UUID.
+function provenRunnerId(result) {
+  if (!result || result.error !== true || !(result.status >= 200 && result.status < 300)) return null;
+  if (typeof result.body !== "string") return null;
+  const match = result.body.match(/"runner"\s*:\s*\{[^{}]*?"id"\s*:\s*"([^"]{36})"/);
+  return match && UUID.test(match[1]) ? match[1] : null;
+}
+
+function reservationOutcome(tokenPath, removed) {
+  return removed
+    ? `The token_file '${tokenPath}' was removed; the same path can be used again.`
+    : `The token_file '${tokenPath}' could NOT be removed: delete it before enrolling again at that path.`;
+}
+
+async function revoke(apiCall, id) {
+  try {
+    const result = await apiCall("DELETE", runnerPath(id), null);
+    if (result && result.error) return { ok: false, detail: `status ${result.status}` };
+    return { ok: true };
+  } catch {
+    return { ok: false, detail: "request error" };
+  }
+}
+
+async function closeQuietly(handle) {
+  try {
+    await handle.close();
+  } catch {
+    // already closed, or the close is what failed
+  }
+}
+
+// Close the handle and remove the file this call created. Removal is by path, so it first
+// checks that the path still names the file identified by `opened`, the stat taken right
+// after the open. Resolves to whether the path no longer holds that file.
+async function discardReservation(fs, handle, tokenPath, opened) {
+  await closeQuietly(handle);
+
+  let current;
+  try {
+    current = await fs.lstat(tokenPath);
+  } catch (err) {
+    return err?.code === "ENOENT";
+  }
+  if (current.ino !== opened.ino || current.dev !== opened.dev) return false;
+
+  try {
+    await fs.unlink(tokenPath);
+    return true;
+  } catch (err) {
+    return err?.code === "ENOENT";
+  }
+}
+
+/** `GET /api/v1/runners`, optionally with revoked runners. */
+export async function listRunners({ include_revoked } = {}, { userKey, apiCall } = {}) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+  const query = include_revoked ? "?include_revoked=true" : "";
+  return apiCall("GET", `${RUNNERS_PATH}${query}`, null);
+}
+
+/** `DELETE /api/v1/runners/:id`: revokes the runner and disconnects its live socket. */
+export async function revokeRunner({ id } = {}, { userKey, apiCall } = {}) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+  if (typeof id !== "string" || id.trim() === "") return refuse("`id` is required.");
+  return apiCall("DELETE", runnerPath(id), null);
+}
+
+/** `GET /api/v1/runners/pool`: the tenant's connected runners, from Presence. */
+export async function runnerPool(_args = {}, { userKey, apiCall } = {}) {
+  if (!userKey) return refuse(MISSING_USER_KEY);
+  return apiCall("GET", RUNNER_POOL_PATH, null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.91.0",
+  "version": "2.92.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",