@tablation/crew 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brad Choate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,10 @@ A standing team of headless agents that picks work off a
 [Tablation](https://tablation.com) board, does it on a machine you control,
 and reports back on the board.
 
+**Documentation: <https://crew.tablation.dev>** — start with
+[Getting started](https://crew.tablation.dev/getting-started). The source is in
+`docs/`.
+
 Each **seat** is a row in the board's Crew table that happens to be a robot,
 with a brief (`prompts/<promptSet>/`, see "Prompt sets" below) and a slice
 of the queue. A seat is named in that table and answers to that name, in the
@@ -207,7 +211,7 @@ crew pause|resume [route] [R]  pause everything, or one role
 crew log [route]               tail the log
 crew inbox [--member NAME]    your tickets across every workspace
 crew connect WS[/PROJECT]     resolve a workspace/project's ids into the state tree
-crew repos add ROUTE PATH     attach a local checkout to a route in crew.yaml (--dry-run previews)
+crew repos add ROUTE PATH     attach a local checkout to a route in crew.yaml, creating its Repos row if missing (--dry-run previews)
 crew repos list ROUTE         the checkouts a route has, and the tracker Repos row each matches
 crew install                  write and load this platform's scheduler unit
 crew uninstall                unload and remove it

package/bin/crew

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// crew — the runner. See src/cli.ts.
+//
+// Runs the built output when it exists, and falls back to running TypeScript
+// directly so a checkout works without a build step. The bash runner this
+// replaces is kept as bin/crew-legacy.sh until cutover is done.
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const built = join(here, '..', 'dist', 'cli.js');
+const source = join(here, '..', 'src', 'cli.ts');
+
+// CREW_FROM_SOURCE=1 skips the bundle even when one exists. crew's own test
+// suite sets it on every CLI it spawns (test/helpers/crew-bin.ts): dist/ is
+// rebuilt by the release's build hook, which runs AFTER the test gate, so
+// without this the gate exercises the previous release's bundle (CREW-988).
+const fromSource = process.env.CREW_FROM_SOURCE === '1' && existsSync(source);
+
+if (existsSync(built) && !fromSource) {
+  await import(pathToFileURL(built).href);
+} else if (existsSync(source)) {
+  // Node >=22.18 strips types natively; older needs --experimental-strip-types.
+  await import(pathToFileURL(source).href);
+} else {
+  console.error('crew: no dist/cli.js and no src/cli.ts — is this a complete checkout?');
+  process.exit(1);
+}

package/dist/cli.js

@@ -576,7 +576,9 @@ var SHIP_KEYS = /* @__PURE__ */ new Set([
   "streamRetentionDays",
   "reposBasePath",
   "relayHost",
-  "relayPort"
+  "relayPort",
+  "relayHttpPort",
+  "relayPublicDomain"
 ]);
 var ROUTE_KEYS = /* @__PURE__ */ new Set([
   "route",
@@ -907,8 +909,10 @@ Create the first of those:
       maxConcurrentAgents,
       streamRetentionDays,
       relayHost: shipRaw.relayHost ? String(shipRaw.relayHost) : void 0,
-      // 2222 matches the relay's own RELAY_SSH_PORT default (docs/RELAY.md).
-      relayPort: shipRaw.relayPort !== void 0 ? Number(shipRaw.relayPort) : 2222
+      // 2222 matches the relay's own RELAY_SSH_PORT default (crew-relay README).
+      relayPort: shipRaw.relayPort !== void 0 ? Number(shipRaw.relayPort) : 2222,
+      relayHttpPort: shipRaw.relayHttpPort !== void 0 ? Number(shipRaw.relayHttpPort) : 443,
+      relayPublicDomain: shipRaw.relayPublicDomain ? String(shipRaw.relayPublicDomain) : void 0
     },
     routes,
     crewHome,
@@ -1868,6 +1872,18 @@ var Tracker = class {
       return void 0;
     }
   }
+  /** Every `Projects` (area) row — what `crew repos add` offers when a new Repos row needs one. */
+  async projectRows() {
+    const model = this.route.resolved?.areaModelId;
+    if (!model) return [];
+    return this.client.records.list(model, { limit: 200 });
+  }
+  /** Create a `Repos` row. Throws when the workspace has no Repos table. */
+  async createRepoRow(fields) {
+    const model = this.route.resolved?.reposModelId;
+    if (!model) throw new Error("this workspace has no Repos table");
+    return this.client.records.create(model, fields);
+  }
   /**
    * The Ships rows of this workspace, if it has a Ships table.
    *
@@ -1944,7 +1960,7 @@ var Tracker = class {
   }
   /**
    * Writes this ship's own tunnel state for Host Passengers (ISSUE-553):
-   * `tunnel_status` (disconnected/connecting/connected) and `mcp_url`, as
+   * `tunnel_status` (disconnected/connecting/connected), as
    * the tunnel client (`tunnel.ts`) brings a workspace's container's tunnel
    * up or down. A no-op, like every other `myShipRow`-backed write here, on
    * a workspace with no Ships table or no row for this ship's name — the
@@ -2838,12 +2854,36 @@ function remoteBranchExists(cwd, remote, branch) {
   return gitOk(cwd, ["rev-parse", "-q", "--verify", `refs/remotes/${remote}/${branch}`]) !== null;
 }
 function findKeyInRange(cwd, key, range) {
+  return keyCommitsInRange(cwd, key, range)[0] ?? null;
+}
+function keyCommitsInRange(cwd, key, range) {
   const keys = Array.isArray(key) ? key : [key];
   const escaped = keys.map((k) => k.replace(/[.[\]{}()*+?^$|\\]/g, "\\$&"));
   const pattern = `(^|[^0-9A-Za-z_-])(${escaped.join("|")})([^0-9]|$)`;
   const out = gitOk(cwd, ["log", range, "--format=%H %s", "--extended-regexp", `--grep=${pattern}`]);
-  if (!out) return null;
-  return out.split("\n")[0]?.split(" ")[0] ?? null;
+  if (!out) return [];
+  return out.split("\n").map((l) => l.split(" ")[0]).filter(Boolean);
+}
+function patchIdOf(cwd, from, to) {
+  try {
+    const diff = execFileSync("git", ["diff", from, to], { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    if (!diff) return null;
+    const out = execFileSync("git", ["patch-id", "--stable"], { cwd, encoding: "utf8", input: diff });
+    return out.split(" ")[0]?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function findSquashOfBranch(cwd, key, branch, base, range) {
+  const candidates = keyCommitsInRange(cwd, key, range);
+  if (candidates.length === 0) return null;
+  const mb = gitOk(cwd, ["merge-base", base, branch]);
+  const branchPatch = mb ? patchIdOf(cwd, mb, branch) : null;
+  for (const sha of candidates) {
+    if (gitOk(cwd, ["diff", "--quiet", branch, sha]) !== null) return sha;
+    if (branchPatch && gitOk(cwd, ["rev-parse", "--verify", "-q", `${sha}^`]) !== null && patchIdOf(cwd, `${sha}^`, sha) === branchPatch) return sha;
+  }
+  return null;
 }
 function isAncestor(cwd, ancestor, descendant) {
   return gitOk(cwd, ["merge-base", "--is-ancestor", ancestor, descendant]) !== null;
@@ -3656,6 +3696,31 @@ function renderEnvironment(i) {
       ...epicsModelId ? [`- Epics: \`${epicsModelId}\``] : []
     );
   }
+  const workspaceId = route.resolved?.workspaceId;
+  if (workspaceId) {
+    const base = route.baseUrl.replace(/\/+$/, "");
+    lines.push(
+      "",
+      `- Workspace id: \`${workspaceId}\``,
+      "",
+      "## Attaching a file to a comment",
+      "",
+      "A screenshot or mockup goes on a comment's `attachments` field, which holds",
+      "Media Library record ids, not URLs. Upload the file first, then put the",
+      "returned `id` in the comment's `attachments` array:",
+      "",
+      "```sh",
+      `curl -s -H "Authorization: Bearer $${API_KEY_VAR}" -H "User-Agent: ${i.userAgent}" \\`,
+      `  -X POST "${base}/api/workspaces/${workspaceId}/files" \\`,
+      '  -F "file=@shot.png;type=image/png" -F targetMediaLibrary=true',
+      "```",
+      "",
+      "The response is JSON with `id` and `storageKey`. `targetMediaLibrary=true`",
+      "means no field type id has to be looked up. If the upload fails, post the HTTP",
+      "status and response body in your comment \u2014 do not write that uploads are",
+      "impossible."
+    );
+  }
   lines.push(
     "",
     "## What the columns are called here",
@@ -4763,6 +4828,25 @@ function planMerge(cwd, tickets, contract, lastReleased, branchFor = (t) => bran
         skipReason: onMain ? "already-merged" : "never-built"
       };
     }
+    const squash = findSquashOfBranch(
+      cwd,
+      referenceKeys(ticket),
+      branch,
+      base,
+      lastReleased ? `${lastReleased}..${base}` : base
+    );
+    if (squash) {
+      return {
+        ticket,
+        branch,
+        entries: [],
+        usedFallback: false,
+        bump: "patch",
+        majorRequested: false,
+        skipReason: "already-merged",
+        mergedSha: squash
+      };
+    }
     const bodies = commitBodies(cwd, `${base}..${branch}`);
     const entries = [...bodies.matchAll(CHANGELOG_LINE)].map((m) => m[1].trim()).filter(Boolean);
     const usedFallback = entries.length === 0;
@@ -4904,6 +4988,8 @@ function summarizeOutcome(o, scope, hadTestHook) {
     case "nothing merged and no release marker":
     case "already contained in the base branch":
       return { scope, tests: "skipped", outcome: "nothing", detail: o.stopped };
+    case "setup failed":
+      return { scope, tests: "skipped", outcome: "nothing", detail: "setup failed \u2014 not tested or deployed" };
     case "build failed":
       return { scope, tests, outcome: "build-failed", detail: "build failed \u2014 not deployed" };
     case "deploy failed":
@@ -5203,9 +5289,12 @@ async function runRelease(o) {
   const unbuildable = [];
   let applied = 0;
   for (const c of decision.merges) {
-    if (!c.branch) {
+    if (!c.branch || c.mergedSha) {
       if (c.skipReason === "already-merged") {
-        o.emit.emit("verified and already merged, waiting on a successful release", { ticket: c.ticket.issue_id });
+        o.emit.emit(
+          `verified and already merged${c.mergedSha ? ` (on the base as ${c.mergedSha.slice(0, 7)})` : ""}, waiting on a successful release`,
+          { ticket: c.ticket.issue_id }
+        );
       } else {
         o.emit.emit("verified but has no branch and nothing on the base names it \u2014 nothing to merge", { ticket: c.ticket.issue_id });
         unbuildable.push(c);
@@ -5262,7 +5351,19 @@ async function runRelease(o) {
     o.emit.emit(
       `${hookLabel(o.repo, "test")} skipped \u2014 release.mode is integrate with no deploy hook, so this "crew deploy" run has nothing to ship`
     );
-  } else if (!o.skipTests && o.repo.hooks.test) {
+  }
+  const gatesNeedSetup = !o.skipTests && o.repo.hooks.test && !(o.isDeployCommand && nothingToDeploy) || o.repo.hooks.build;
+  if (o.repo.hooks.setup && gatesNeedSetup) {
+    if (o.dryRun) o.emit.emit(`would run setup: ${hookLabel(o.repo, "setup")}`);
+    else {
+      const r = await hook(o, "setup");
+      if (r && r.code !== 0) {
+        o.emit.error(`setup FAILED (exit ${r.code}) \u2014 not testing or deploying; the target stays on the previous release`);
+        return { merged, conflicts, unbuildable, deployed: false, stopped: "setup failed", decision };
+      }
+    }
+  }
+  if (!(o.isDeployCommand && nothingToDeploy) && !o.skipTests && o.repo.hooks.test) {
     if (o.dryRun) o.emit.emit(`would run the test gate: ${hookLabel(o.repo, "test")}`);
     else {
       let r = await hook(o, "test");
@@ -5281,6 +5382,7 @@ async function runRelease(o) {
   if (majorRequested) {
     o.emit.warn("a branch asked for a MAJOR bump \u2014 honoured as minor; major is the operator's call");
   }
+  const preBump = headSha(o.cwd);
   const version = await bump(o, size) ?? void 0;
   if (!version && o.dryRun && o.repo.hooks.bump) {
     o.emit.emit("would then commit the version bump and changelog");
@@ -5303,6 +5405,10 @@ async function runRelease(o) {
       }
       if (r && r.code !== 0) {
         o.emit.error("build failed \u2014 not deploying");
+        if (version && !o.dryRun && headSha(o.cwd) !== preBump) {
+          git(o.cwd, ["reset", "--hard", preBump]);
+          o.emit.warn(`dropped the unreleased version commit for ${version} (reset ${o.repo.branch.base} to ${preBump.slice(0, 8)}) so a retry starts clean`);
+        }
         return { merged, conflicts, unbuildable, version, deployed: false, stopped: "build failed", decision };
       }
     }
@@ -5519,6 +5625,13 @@ function describeRelease(o, route) {
       detail: "the target stays on the previous release"
     };
   }
+  if (o.stopped === "setup failed") {
+    return {
+      level: "fail",
+      headline: `${route}: release blocked \u2014 setup failed`,
+      detail: "dependencies could not be installed in the release checkout; the target stays on the previous release"
+    };
+  }
   if (o.stopped === "deploy failed") {
     return { level: "fail", headline: `${route}: deploy FAILED`, detail: "nothing new is live" };
   }
@@ -6912,7 +7025,7 @@ function planRepoAdd(i) {
     throw new ReposError(`${target} is already configured on route ${i.route}`);
   }
   const matched = matchRepoName(i.origin, i.resolved);
-  const name = matched ?? basename5(target);
+  const name = matched ?? i.name ?? basename5(target);
   let warning;
   if (!matched) {
     const known = Object.values(i.resolved?.repoNames ?? {});
@@ -6937,11 +7050,39 @@ function planRepoAdd(i) {
     m.set("dir", target);
     mode = "dir";
   }
-  return { text: String(doc), mode, name, block: renderBlock(m), warning };
+  return { text: String(doc), mode, name, block: renderBlock(m), warning, unmatched: !matched };
 }
 function renderBlock(m) {
   return stringify2([m.toJSON()]).trimEnd();
 }
+var LOCAL_RELEASE_MODES = /* @__PURE__ */ new Set(["integrate", "external"]);
+function planRepoRow(i) {
+  const remote = normalizeRemote(i.origin);
+  if (!remote) throw new ReposError(`cannot derive an owner/repo from origin "${i.origin}"`);
+  const mode = i.spec?.releaseMode;
+  return {
+    name: i.name,
+    remote,
+    platform: i.spec?.platform ?? "unix",
+    release_mode: mode ? LOCAL_RELEASE_MODES.has(mode) ? "local" : mode : "local",
+    ci_provider: i.spec?.ciProvider ?? "none",
+    enabled: true,
+    project_id: i.projectId
+  };
+}
+function resolveRepoProject(projects, opt, routeAreaId) {
+  if (opt) {
+    const want = opt.toLowerCase();
+    const hit = projects.find((p) => p.id === opt || p.name?.toLowerCase() === want);
+    if (!hit) throw new ReposError(`no Projects row "${opt}" (have: ${projects.map((p) => p.name ?? p.id).join(", ") || "none"})`);
+    return hit.id;
+  }
+  if (routeAreaId) return routeAreaId;
+  if (projects.length === 1) return projects[0].id;
+  throw new ReposError(
+    `cannot tell which project the new Repos row belongs to \u2014 pass --project <name> (have: ${projects.map((p) => p.name ?? p.id).join(", ") || "none"}), or --no-create to skip creating it`
+  );
+}
 
 // src/doctor-fix.ts
 import { parseDocument as parseDocument2 } from "yaml";
@@ -7299,12 +7440,24 @@ function syncAllPassengerCheckouts(cfg) {
 // src/tunnel.ts
 import { spawn as spawn3 } from "child_process";
 import { existsSync as existsSync16, mkdirSync as mkdirSync8, readFileSync as readFileSync10, writeFileSync as writeFileSync7, unlinkSync as unlinkSync3, readdirSync as readdirSync3 } from "fs";
+import { randomInt } from "crypto";
 import { join as join15 } from "path";
 var DEFAULT_SPAWN_OPTIONS = { stdio: "ignore", detached: true };
 var defaultSpawn = (cmd, args) => spawn3(cmd, args, DEFAULT_SPAWN_OPTIONS);
-var SECRET_MARKER = "-secret-";
+var SLUG_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+var SLUG_LENGTH = 12;
+function generateTunnelSlug() {
+  let out = "";
+  for (let i = 0; i < SLUG_LENGTH; i++) out += SLUG_ALPHABET[randomInt(SLUG_ALPHABET.length)];
+  return out;
+}
 function bindAddrFor(o) {
-  return o.mcpSecret ? `workspace-${o.workspaceId}${SECRET_MARKER}${o.mcpSecret}` : `workspace-${o.workspaceId}`;
+  const base = `workspace-${o.workspaceId}-slug-${o.slug}-key-${o.apiKey}`;
+  return o.mcpSecret ? `${base}-secret-${o.mcpSecret}` : base;
+}
+function publicUrlFor(slug, relayHost, relayHttpPort, relayPublicDomain) {
+  const domain = relayPublicDomain ?? relayHost.replace(/^.*@/, "");
+  return `https://${slug}.${domain}${relayHttpPort === 443 ? "" : `:${relayHttpPort}`}/mcp`;
 }
 function sshArgsFor(o) {
   return [
@@ -7372,6 +7525,13 @@ function writePersistedTunnel(stateDir, state) {
   writeFileSync7(path, `${JSON.stringify(state, null, 2)}
 `);
 }
+function updatePersistedTunnel(stateDir, workspaceId, patch2) {
+  const existing = readPersistedTunnel(stateDir, workspaceId);
+  if (existing) writePersistedTunnel(stateDir, { ...existing, ...patch2 });
+}
+function rotatePersistedSlug(stateDir, workspaceId) {
+  updatePersistedTunnel(stateDir, workspaceId, { slug: generateTunnelSlug() });
+}
 function removePersistedTunnel(stateDir, workspaceId) {
   const path = tunnelStatePath(stateDir, workspaceId);
   try {
@@ -7393,11 +7553,13 @@ function syncPassengerTunnels(plans, relayHost, relayPort, privateKeyPath, state
     const existing = readPersistedTunnel(stateDir, plan.workspaceId);
     const currentSecret = mcpSecrets.get(plan.workspaceId);
     const secretUnchanged = (existing?.mcpSecret ?? void 0) === (currentSecret ?? void 0);
-    if (existing && alive(existing.pid) && existing.mountsHash === plan.mountsHash && secretUnchanged) {
+    const slug = existing?.slug ?? generateTunnelSlug();
+    const slugUnchanged = existing?.liveSlug === slug;
+    if (existing && alive(existing.pid) && existing.mountsHash === plan.mountsHash && secretUnchanged && slugUnchanged) {
       if (existing.status === "connecting") {
         const settled = { ...existing, status: "connected" };
         writePersistedTunnel(stateDir, settled);
-        deps.onStatus?.(plan.workspaceId, "connected");
+        deps.onStatus?.(plan.workspaceId, "connected", settled);
       }
       continue;
     }
@@ -7407,11 +7569,18 @@ function syncPassengerTunnels(plans, relayHost, relayPort, privateKeyPath, state
       } catch {
       }
     }
+    const apiKey = deps.apiKeys?.get(plan.workspaceId);
+    if (!apiKey) {
+      deps.onStatus?.(plan.workspaceId, "disconnected", existing);
+      continue;
+    }
     let settledStatus = "connecting";
     const tunnel = startTunnel({
       relayHost,
       relayPort,
       workspaceId: plan.workspaceId,
+      slug,
+      apiKey,
       localPort: plan.port,
       privateKeyPath,
       mcpSecret: currentSecret,
@@ -7420,16 +7589,21 @@ function syncPassengerTunnels(plans, relayHost, relayPort, privateKeyPath, state
         settledStatus = s;
       }
     });
-    writePersistedTunnel(stateDir, {
+    const started = {
       pid: tunnel.pid ?? -1,
       containerName: plan.containerName,
       workspaceId: plan.workspaceId,
       mountsHash: plan.mountsHash,
       startedAt: (/* @__PURE__ */ new Date()).toISOString(),
       status: settledStatus,
-      mcpSecret: currentSecret
-    });
-    deps.onStatus?.(plan.workspaceId, settledStatus);
+      mcpSecret: currentSecret,
+      slug,
+      liveSlug: slug,
+      endpointId: existing?.endpointId,
+      registeredKey: existing?.registeredKey
+    };
+    writePersistedTunnel(stateDir, started);
+    deps.onStatus?.(plan.workspaceId, settledStatus, started);
   }
   for (const workspaceId of readAllPersistedWorkspaceIds(stateDir)) {
     if (plannedIds.has(workspaceId)) continue;
@@ -7441,7 +7615,7 @@ function syncPassengerTunnels(plans, relayHost, relayPort, privateKeyPath, state
       }
     }
     removePersistedTunnel(stateDir, workspaceId);
-    deps.onStatus?.(workspaceId, "disconnected");
+    deps.onStatus?.(workspaceId, "disconnected", existing);
   }
 }
 function readAllPersistedWorkspaceIds(stateDir) {
@@ -7450,6 +7624,119 @@ function readAllPersistedWorkspaceIds(stateDir) {
   return readdirSync3(dir).filter((f) => f.endsWith(".json") && !f.endsWith("-sync.json")).map((f) => f.slice(0, -".json".length));
 }
 
+// src/mcp-endpoint-registry.ts
+import { createHash as createHash5 } from "crypto";
+function endpointsUrl(api, workspaceId, id) {
+  const base = `${api.baseUrl.replace(/\/+$/, "")}/api/workspaces/${workspaceId}/mcp-endpoints`;
+  return id ? `${base}/${id}` : base;
+}
+async function call(api, method, url, body) {
+  const f = api.fetchFn ?? fetch;
+  return f(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${api.apiKey}`,
+      "User-Agent": api.userAgent ?? "Mozilla/5.0 CrewAgent",
+      ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+    },
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+}
+function bodyFor(d, forPatch) {
+  const body = { label: d.label, url: d.url };
+  if (d.mcpSecret) body.authorizationHeader = `Bearer ${d.mcpSecret}`;
+  else if (forPatch) body.authorizationHeader = null;
+  return body;
+}
+async function create(api, workspaceId, d) {
+  const res = await call(api, "POST", endpointsUrl(api, workspaceId), bodyFor(d, false));
+  if (res.status === 403) return { kind: "forbidden" };
+  if (!res.ok) return { kind: "error", message: `register endpoint: ${res.status} ${res.statusText}` };
+  const row = await res.json();
+  if (!row.id) return { kind: "error", message: "register endpoint: response carried no id" };
+  return { kind: "ok", endpointId: row.id, action: "created" };
+}
+async function registerEndpoint(api, workspaceId, storedId, d) {
+  try {
+    if (!storedId) return await create(api, workspaceId, d);
+    const res = await call(api, "PATCH", endpointsUrl(api, workspaceId, storedId), bodyFor(d, true));
+    if (res.status === 403) return { kind: "forbidden" };
+    if (res.status === 404) {
+      const made = await create(api, workspaceId, d);
+      return made.kind === "ok" ? { ...made, action: "recreated" } : made;
+    }
+    if (!res.ok) return { kind: "error", message: `update endpoint: ${res.status} ${res.statusText}` };
+    return { kind: "ok", endpointId: storedId, action: "updated" };
+  } catch (e) {
+    return { kind: "error", message: e.message };
+  }
+}
+async function removeEndpoint(api, workspaceId, storedId) {
+  try {
+    const res = await call(api, "DELETE", endpointsUrl(api, workspaceId, storedId));
+    if (res.status === 403) return { kind: "forbidden" };
+    if (res.ok || res.status === 404) return { kind: "ok" };
+    return { kind: "error", message: `remove endpoint: ${res.status} ${res.statusText}` };
+  } catch (e) {
+    return { kind: "error", message: e.message };
+  }
+}
+async function probeEndpointAccess(api, workspaceId) {
+  try {
+    const res = await call(api, "GET", endpointsUrl(api, workspaceId));
+    if (res.ok) return "ok";
+    if (res.status === 403) return "forbidden";
+    return { error: `${res.status} ${res.statusText}` };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+var REGISTER_MCP_ENDPOINTS_HINT = "give this key's role the REGISTER_MCP_ENDPOINTS capability, e.g. via the group that holds the Crew project role";
+function registrationKey(url, mcpSecret) {
+  return createHash5("sha256").update(`${url}
+${mcpSecret ?? ""}`).digest("hex").slice(0, 16);
+}
+async function reconcileEndpoint(workspaceId, d) {
+  const st = readPersistedTunnel(d.stateDir, workspaceId);
+  if (!st || st.status !== "connected" || !st.slug) return;
+  const url = d.urlFor(st.slug);
+  const key = registrationKey(url, st.mcpSecret);
+  if (st.endpointId && st.registeredKey === key) return;
+  const api = d.apiFor(workspaceId);
+  if (!api) {
+    d.warn(`no API key known for workspace ${workspaceId} \u2014 cannot register its MCP endpoint`);
+    return;
+  }
+  const out = await registerEndpoint(api, workspaceId, st.endpointId, {
+    label: `Ship: ${d.shipName}`,
+    url,
+    mcpSecret: st.mcpSecret
+  });
+  if (out.kind === "ok") {
+    updatePersistedTunnel(d.stateDir, workspaceId, { endpointId: out.endpointId, registeredKey: key });
+  } else if (out.kind === "forbidden") {
+    d.warn(`could not register this ship's MCP endpoint in workspace ${workspaceId}: 403 \u2014 ${REGISTER_MCP_ENDPOINTS_HINT}`);
+  } else {
+    d.warn(`could not register this ship's MCP endpoint in workspace ${workspaceId}: ${out.message}`);
+  }
+}
+async function unregisterEndpoint(workspaceId, info, d) {
+  if (!info?.endpointId) return;
+  const api = d.apiFor(workspaceId);
+  if (!api) {
+    d.warn(`no API key known for workspace ${workspaceId} \u2014 cannot remove its MCP endpoint`);
+    return;
+  }
+  const out = await removeEndpoint(api, workspaceId, info.endpointId);
+  if (out.kind === "ok") {
+    updatePersistedTunnel(d.stateDir, workspaceId, { endpointId: void 0, registeredKey: void 0 });
+  } else {
+    d.warn(
+      `could not remove this ship's MCP endpoint in workspace ${workspaceId}: ` + (out.kind === "forbidden" ? `403 \u2014 ${REGISTER_MCP_ENDPOINTS_HINT}` : out.message)
+    );
+  }
+}
+
 // src/passenger-sync-daemon.ts
 import { createServer as createHttpServer } from "http";
 import { spawn as spawn4 } from "child_process";
@@ -8049,6 +8336,35 @@ if (command === "passenger-sync-daemon") {
   }, parseTicketNumber = function(input) {
     const m = /^(?:[A-Za-z]+-)?(\d+)$/.exec(input.trim());
     return m ? m[1] : null;
+  }, passengerApiKeys = function(routes) {
+    const keys = /* @__PURE__ */ new Map();
+    for (const r of routes) {
+      const ws = r.resolved?.workspaceId;
+      if (!ws) continue;
+      try {
+        keys.set(ws, resolveApiKey(r));
+      } catch {
+      }
+    }
+    return keys;
+  }, endpointApiFor = function(routes) {
+    return (workspaceId) => {
+      const r = routes.find((x) => x.resolved?.workspaceId === workspaceId);
+      if (!r) return void 0;
+      try {
+        return { baseUrl: r.baseUrl || DEFAULT_BASE_URL, apiKey: resolveApiKey(r), userAgent: cfg.ship.userAgent };
+      } catch {
+        return void 0;
+      }
+    };
+  }, endpointReconcileDeps = function(routes, relayHost) {
+    return {
+      stateDir: cfg.ship.stateDir,
+      shipName: cfg.ship.name,
+      apiFor: endpointApiFor(routes),
+      urlFor: (slug) => publicUrlFor(slug, relayHost, cfg.ship.relayHttpPort, cfg.ship.relayPublicDomain),
+      warn: (m) => emit.warn(m, { step: "passengers" })
+    };
   }, reportUnplaceable = function(c, unplaceable, verified, emit2) {
     if (unplaceableReported.has(c.route)) return;
     unplaceableReported.add(c.route);
@@ -8057,7 +8373,7 @@ if (command === "passenger-sync-daemon") {
       else emit2.emit(note.message, { step: "release" });
     }
   };
-  requireArmed2 = requireArmed, parseTicketNumber2 = parseTicketNumber, reportUnplaceable2 = reportUnplaceable;
+  requireArmed2 = requireArmed, parseTicketNumber2 = parseTicketNumber, passengerApiKeys2 = passengerApiKeys, endpointApiFor2 = endpointApiFor, endpointReconcileDeps2 = endpointReconcileDeps, reportUnplaceable2 = reportUnplaceable;
   let cfg;
   let firstRun;
   try {
@@ -8162,13 +8478,24 @@ if (command === "passenger-sync-daemon") {
           const { privateKeyPath } = ensureShipSshKeypair(cfg.ship.stateDir);
           const plans = planContainers(cfg);
           const mcpSecrets = new Map([...syncEndpoints].map(([workspaceId, e]) => [workspaceId, e.secret]));
-          syncPassengerTunnels(plans, cfg.ship.relayHost, cfg.ship.relayPort, privateKeyPath, cfg.ship.stateDir, mcpSecrets, {
-            onStatus: (workspaceId, status2) => {
+          const relayHost = cfg.ship.relayHost;
+          const reconcile = endpointReconcileDeps(passengerRoutes, relayHost);
+          const pending = [];
+          syncPassengerTunnels(plans, relayHost, cfg.ship.relayPort, privateKeyPath, cfg.ship.stateDir, mcpSecrets, {
+            apiKeys: passengerApiKeys(passengerRoutes),
+            onStatus: (workspaceId, status2, info) => {
               const owningRoute = passengerRoutes.find((r) => r.resolved?.workspaceId === workspaceId);
               if (!owningRoute) return;
-              new Tracker(owningRoute, cfg.ship).updateTunnelState(cfg.ship.name, { tunnel_status: status2 }).catch((e) => emit.warn(`could not write tunnel_status: ${e.message}`, { step: "passengers" }));
+              pending.push(
+                new Tracker(owningRoute, cfg.ship).updateTunnelState(cfg.ship.name, { tunnel_status: status2 }).catch((e) => {
+                  emit.warn(`could not write tunnel_status: ${e.message}`, { step: "passengers" });
+                })
+              );
+              if (status2 === "disconnected") pending.push(unregisterEndpoint(workspaceId, info, reconcile));
             }
           });
+          for (const plan of plans) pending.push(reconcileEndpoint(plan.workspaceId, reconcile));
+          await Promise.all(pending);
         } catch (e) {
           emit.warn(`passenger tunnel sync failed: ${e.message}`, { step: "passengers" });
         }
@@ -9232,7 +9559,7 @@ ${changed2.map((c) => `  - ${c}
       const sub = positional[1];
       const routeName = positional[2];
       const usage2 = () => {
-        process.stderr.write("crew repos add <workspace/project> <path> [--dry-run]\ncrew repos list <workspace/project>\n");
+        process.stderr.write("crew repos add <workspace/project> <path> [--name N] [--project P] [--dry-run] [--no-create]\ncrew repos list <workspace/project>\n");
         process.exit(2);
       };
       if (sub !== "add" && sub !== "list" || !routeName || sub === "add" && !positional[3]) usage2();
@@ -9253,9 +9580,9 @@ ${changed2.map((c) => `  - ${c}
           if (repos.length === 0) process.stdout.write(`route ${routeName} has no checkout configured \u2014 \`crew repos add ${routeName} <path>\`
 `);
           for (const r of repos) {
-            const origin = originOf(r.dir);
-            const row = matchRepoName(origin, resolvedRemotes);
-            const note = !existsSync18(r.dir) ? "missing on disk" : row ? `Repos row: ${row}` : `no Repos row matches ${normalizeRemote(origin) ?? "this checkout (no origin remote)"}`;
+            const origin2 = originOf(r.dir);
+            const row = matchRepoName(origin2, resolvedRemotes);
+            const note = !existsSync18(r.dir) ? "missing on disk" : row ? `Repos row: ${row}` : `no Repos row matches ${normalizeRemote(origin2) ?? "this checkout (no origin remote)"}`;
             process.stdout.write(`${r.name}	${r.dir}	${note}
 `);
           }
@@ -9264,22 +9591,60 @@ ${changed2.map((c) => `  - ${c}
         const target = resolvePath(positional[3].replace(/^~(?=\/|$)/, homedir4()));
         const top = existsSync18(target) ? gitOk(target, ["rev-parse", "--show-toplevel"]) : null;
         if (!top) throw new ReposError(`${target} is not a git checkout`);
+        const origin = originOf(top);
         const plan = planRepoAdd({
           text,
           base,
           route: routeName,
           path: top,
-          origin: originOf(top),
+          origin,
           resolved: resolvedRemotes,
+          name: value("name"),
           nameForExisting: (d) => matchRepoName(originOf(d), resolvedRemotes)
         });
-        if (plan.warning) process.stderr.write(`crew repos: warning \u2014 ${plan.warning}
+        let rowTracker;
+        let rowPayload;
+        if (plan.unmatched && origin && !flag("no-create")) {
+          const planned = loadConfig(CREW_HOME, cfg.configFile, { text: plan.text, allowNoRoutes: true });
+          const planRoute = planned.routes.find((r) => r.route === routeName);
+          if (!planRoute) throw new ReposError(`route ${routeName} did not load from the planned config; use --no-create`);
+          try {
+            rowTracker = new Tracker(planRoute, cfg.ship);
+          } catch (e) {
+            if (e instanceof ConfigError) throw new ReposError(`${e.message}; or pass --no-create`);
+            throw e;
+          }
+          const projectId = resolveRepoProject(await rowTracker.projectRows(), value("project"), planRoute.resolved?.areaId);
+          let spec;
+          try {
+            const rc = loadRepoConfig(top);
+            if (rc) spec = { platform: rc.platform, releaseMode: rc.release.mode, ciProvider: rc.release.ci.provider };
+          } catch {
+          }
+          rowPayload = planRepoRow({ name: plan.name, origin, spec, projectId });
+        } else if (plan.warning) {
+          process.stderr.write(`crew repos: warning \u2014 ${plan.warning}
 `);
+        }
         if (dryRun) {
           process.stdout.write(`${plan.block}
+`);
+          if (rowPayload) process.stdout.write(`would create Repos row: ${JSON.stringify(rowPayload)}
 `);
           break;
         }
+        if (rowTracker && rowPayload) {
+          const created = await rowTracker.createRepoRow(rowPayload);
+          process.stdout.write(`created Repos row ${String(rowPayload.name)} (${String(rowPayload.remote)}) ${created.id}
+`);
+          if (existsSync18(resolvedFile)) {
+            const raw = JSON.parse(readFileSync12(resolvedFile, "utf8"));
+            raw.repoNames = { ...raw.repoNames, [created.id]: String(rowPayload.name) };
+            raw.repoRemotes = { ...raw.repoRemotes, [created.id]: String(rowPayload.remote) };
+            writeFileSync9(resolvedFile, `${JSON.stringify(raw, null, 2)}
+`);
+          }
+        }
         writeFileSync9(cfg.configFile, plan.text);
         process.stdout.write(`added ${top} to ${routeName} as ${plan.mode === "dir" ? "dir" : `repos.${plan.name}`} in ${cfg.configFile}
 `);
@@ -9406,7 +9771,7 @@ ${reconstruction.prompt}
         }
         let result;
         try {
-          result = await loginWithDeviceCode(baseUrl, {
+          result = await loginWithDeviceCode(`${baseUrl}/api`, {
             deviceName: `crew on ${hostname2()}`,
             onCode: (info) => {
               process.stderr.write(
@@ -9856,6 +10221,7 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
         );
         break;
       }
+      rotatePersistedSlug(cfg.ship.stateDir, workspaceId);
       if (hasLiveTunnel) {
         try {
           process.kill(existing.pid, "SIGTERM");
@@ -9863,12 +10229,21 @@ Signed in as ${result.identity.email} \u2014 minted an API key in workspace "${r
         }
       }
       const { privateKeyPath } = ensureShipSshKeypair(cfg.ship.stateDir);
+      const rotateReconcile = endpointReconcileDeps([route], cfg.ship.relayHost);
+      const rotatePending = [];
       syncPassengerTunnels(plans, cfg.ship.relayHost, cfg.ship.relayPort, privateKeyPath, cfg.ship.stateDir, /* @__PURE__ */ new Map(), {
-        onStatus: (wsId, status2) => {
-          new Tracker(route, cfg.ship).updateTunnelState(cfg.ship.name, { tunnel_status: status2 }).catch((e) => emit.warn(`could not write tunnel_status: ${e.message}`, { step: "passengers" }));
+        apiKeys: passengerApiKeys([route]),
+        onStatus: (wsId, status2, info) => {
+          rotatePending.push(
+            new Tracker(route, cfg.ship).updateTunnelState(cfg.ship.name, { tunnel_status: status2 }).catch((e) => {
+              emit.warn(`could not write tunnel_status: ${e.message}`, { step: "passengers" });
+            })
+          );
+          if (status2 === "disconnected") rotatePending.push(unregisterEndpoint(wsId, info, rotateReconcile));
         }
       });
-      emit.emit(`rotated the passenger tunnel for ${route.route} \u2014 a fresh public URL will be minted on reconnect`);
+      await Promise.all(rotatePending);
+      emit.emit(`rotated the passenger tunnel for ${route.route} \u2014 it reconnects under a fresh slug and the registered endpoint follows on the next passengers cycle`);
       break;
     }
     case "unassign": {
@@ -10197,6 +10572,23 @@ crew manifest:     ${seats2.length ? seats2.map((c) => c.name).join(", ") : "non
             "                   `ssh-keygen` is required to mint this ship's tunnel identity \u2014 install OpenSSH, then re-run `crew connect` to sync a key onto this workspace's Ships row.\n"
           );
         }
+        if (cfg.ship.relayHost) {
+          for (const r of passengerRoutes) {
+            const ws = r.resolved?.workspaceId;
+            const slug = ws ? readPersistedTunnel(cfg.ship.stateDir, ws)?.slug : void 0;
+            if (!ws) continue;
+            process.stdout.write(
+              `                   ${r.route} url: ${slug ? publicUrlFor(slug, cfg.ship.relayHost, cfg.ship.relayHttpPort, cfg.ship.relayPublicDomain) : "not minted yet (first tunnel cycle creates it)"}
+`
+            );
+            const api = endpointApiFor([r])(ws);
+            if (!api) continue;
+            const probe = await probeEndpointAccess(api, ws);
+            process.stdout.write(
+              `                   ${r.route} mcp endpoints: ` + (probe === "ok" ? "OK (key may register its endpoint)" : probe === "forbidden" ? `403 \u2014 ${REGISTER_MCP_ENDPOINTS_HINT}` : `could not check (${probe.error})`) + "\n"
+            );
+          }
+        }
         for (const r of passengerRoutes) {
           const included = passengerRepoTargets(r);
           process.stdout.write(
@@ -10218,4 +10610,7 @@ crew manifest:     ${seats2.length ? seats2.map((c) => c.name).join(", ") : "non
 }
 var requireArmed2;
 var parseTicketNumber2;
+var passengerApiKeys2;
+var endpointApiFor2;
+var endpointReconcileDeps2;
 var reportUnplaceable2;

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "@tablation/crew",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A standing team of headless agents that picks work off a Tablation board, does it on a machine you control, and reports back.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rightdesign/crew.git"
+  },
+  "homepage": "https://github.com/rightdesign/crew#readme",
+  "bugs": {
+    "url": "https://github.com/rightdesign/crew/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -15,9 +23,11 @@
   },
   "files": [
     "dist",
+    "bin",
     "prompts",
     "crew.example.yaml",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
@@ -30,13 +40,16 @@
     "@types/node": "^22.10.0",
     "tsup": "^8.3.5",
     "tsx": "^4.23.12",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitepress": "^1.6.4"
   },
   "scripts": {
     "build": "tsup src/cli.ts --format esm --clean",
     "build:binaries": "scripts/build-binaries.sh",
     "dev": "tsx src/cli.ts",
     "test": "node --test --experimental-strip-types test/*.test.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs"
   }
 }

package/prompts/default/personas/common.md

@@ -388,7 +388,8 @@ if `report_type` is either of those.
    lists, etc. when that's clearer than a plain sentence. If a screenshot
    would help explain something (a UI verification result, a rendering
    bug), attach it via the Comments table's `attachments` field rather than
-   just describing it in text.
+   just describing it in text. The Environment section's "Attaching a file to
+   a comment" recipe says how to upload the file and get the id to put there.
 4a. **Look at the ticket's attachments before you start.** A ticket (and any
    of its comments) may carry an `attachments` value: a list of Media Library
    record ids, not URLs. A bare uuid array is not "nothing to see" — it is

package/prompts/default/personas/lane-design.md

@@ -57,10 +57,14 @@ stopping for this run, do the following instead:
   deliberately left out. Attach images via the Comments table's `attachments`
   field — a described mockup is not a shown one. Render your mockup to PNG
   with Playwright if it only exists as markup, in whatever way fits this
-  repo's own front-end stack. If a canvas Artifact published, include its
-  URL in the comment body too, but never *only* the URL: this session is
-  headless and Artifact publishing may be unavailable, so the screenshots
-  are the deliverable that has to work either way.
+  repo's own front-end stack, then upload it with the recipe under
+  "Attaching a file to a comment" in the Environment section. The PNG
+  upload is a required part of a finished design pass; a text wireframe
+  alone does not satisfy this step. If a canvas Artifact published, include
+  its URL in the comment body too, but never *only* the URL — the Artifact
+  canvas is optional, the PNG is not. If the upload itself fails, post the
+  HTTP status and response body in the comment rather than a sentence
+  saying uploads are impossible.
 - **3.4c — Hand it to the operator, always, one of two ways.** Every design
   pass ends here — every time, not only when the direction is a product
   call — but which of the two endings applies depends on whether you were

package/prompts/dev-qa/personas/common.md

@@ -369,7 +369,8 @@ if `report_type` is either of those.
    lists, etc. when that's clearer than a plain sentence. If a screenshot
    would help explain something (a UI verification result, a rendering
    bug), attach it via the Comments table's `attachments` field rather than
-   just describing it in text.
+   just describing it in text. The Environment section's "Attaching a file to
+   a comment" recipe says how to upload the file and get the id to put there.
 4a. **Look at the ticket's attachments before you start.** A ticket (and any
    of its comments) may carry an `attachments` value: a list of Media Library
    record ids, not URLs. A bare uuid array is not "nothing to see" — it is