ccdeck 3.43.4 → 3.45.0

package/src/server/index.mjs

@@ -19,7 +19,7 @@ import { challengeDeck, challengeProof, isProcessAlive } from "./deck-probe.mjs"
 export { challengeDeck, challengeProof, isProcessAlive };
 // The gates in front of the route table — see src/server/request-gates.mjs,
 // which also holds the per-process token the strictest of them checks.
-import { GUARDED_READS, OPEN_MUTATIONS, isAuthorizedDataRead, isAuthorizedMutation, isTrustedMutation, isTrustedRead } from "./request-gates.mjs";
+import { OPEN_MUTATIONS, isAuthorizedDataRead, isAuthorizedMutation, isGuardedRead, isTrustedMutation, isTrustedRead } from "./request-gates.mjs";
 import { trafficCapture } from "./traffic-radar-capture.mjs";
 import { trafficRadar } from "./traffic-radar.mjs";
 import { handleTrafficCapture, isAuthorizedTrafficIngest } from "./traffic-radar-routes.mjs";
@@ -29,6 +29,8 @@ export { MAX_BUFFER, MAX_BUFFER_CHARS, MAX_RING_ENTRIES, payloadChars } from "./
 // The ring itself — what it holds, how it numbers them, and the eviction that
 // keeps those bounds — private behind its operations. See event-ring.mjs.
 import { eventsSince } from "./event-ring.mjs";
+// The same ring folded to one row per session, for `ccdeck sessions` (#2183).
+import { summarizeSessions } from "./session-summary.mjs";
 // Exported from this file before they moved, and still.
 export { eventBufferStats, eventsSince } from "./event-ring.mjs";
 // The one door every event comes through, and what it does to each on the way
@@ -36,6 +38,7 @@ export { eventBufferStats, eventsSince } from "./event-ring.mjs";
 // routes below: it connects pushEvent to event-sink.mjs as it loads, and the
 // boot replay pushes through that sink before any route has run.
 import "./event-pipeline.mjs";
+import { stopCodexEnrichment } from "./codex-enrichment.mjs";
 // POST /api/event, GET /events and GET /api/events — see event-routes.mjs.
 import { handleEventIngest, handleSse, writeJsonArray } from "./event-routes.mjs";
 // Exported from this file before it moved, and still.
@@ -159,6 +162,7 @@ import { send, sendInternalError } from "./http-io.mjs";
 export { sendInternalError };
 // The accounts surface's routes — see account-routes.mjs. The boot wires the
 // stale-copy repair and starts auto-switch through the same module.
+import { handleStopContinue, handleStopContinueRead } from "./stop-continue.mjs";
 import { cswapAutoModule, getProjectRollup, handleAccountLoginState, handleAccountProjects, handleClaudeAccountAdmin, handleClaudeAccountSwitch, handleClaudeAccounts, handleCswapAuto, handleCswapAutoAction, wireAccountOrigins, wireStaleCopyRepair } from "./account-routes.mjs";
 // Browser Watch's three routes — see browser-watch-routes.mjs.
 import { handleBrowserWatch, handleBrowserWatchDismiss, handleBrowserWatchSettings } from "./browser-watch-routes.mjs";
@@ -169,6 +173,9 @@ import { startToolAudit } from "./tool-audit.mjs";
 import { handleToolAudit } from "./tool-audit-routes.mjs";
 import { startQuotaHistory } from "./quota-history.mjs";
 import { handleCcusage, handleCcusageSession, handleCodexQuota, handleCodexUsage, handleProviderStatus, handleQuota, handleQuotaHistory } from "./usage-routes.mjs";
+// Connected trackers (#2178) and each provider's own reads. See
+// integrations/routes.mjs; nothing in it is shared with paired decks.
+import { handleIntegrations } from "./integrations/routes.mjs";
 // The port fallback, one listen attempt, and the words for a failed one — see
 // listen.mjs. The loop that uses them is startServer's.
 import { listenFailure, portRetryable, randomPort, tryListen } from "./listen.mjs";
@@ -297,7 +304,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     // gate above was written for a sandboxed subprocess with loopback egress,
     // and that caller was reading the ring through a GET the whole time.
     if ((req.method === "GET" || req.method === "HEAD")
-      && GUARDED_READS.has(url.pathname) && !isAuthorizedDataRead(req)) {
+      && isGuardedRead(url.pathname) && !isAuthorizedDataRead(req)) {
       return send(res, 401, { error: "unauthenticated" });
     }
 
@@ -389,6 +396,10 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "POST" && url.pathname === "/api/claude-accounts/switch") return guard(handleClaudeAccountSwitch(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/claude-accounts/login")  return guard(handleAccountLoginState(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/claude-accounts/admin")  return guard(handleClaudeAccountAdmin(req, res), res);
+    // Continue a session whose turn stopped on a login or a usage limit (#2193):
+    // the gate's evidence and each session's outcome, and the press itself.
+    if (req.method === "GET"  && url.pathname === "/api/stop-continue") return guard(handleStopContinueRead(req, res), res);
+    if (req.method === "POST" && url.pathname === "/api/stop-continue") return guard(handleStopContinue(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/cswap-auto")  return guard(handleCswapAuto(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/cswap-auto")  return guard(handleCswapAutoAction(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/claude-fm")   return guard(handleClaudeFm(req, res), res);
@@ -401,6 +412,7 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "GET"  && url.pathname === "/api/best-of-nostalgia") return guard(handleBestOfNostalgia(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/good-life-radio") return guard(handleGoodLifeRadio(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/cafe-music-bgm") return guard(handleCafeMusicBgm(req, res), res);
+    if (url.pathname === "/api/integrations" || url.pathname.startsWith("/api/integrations/")) return guard(handleIntegrations(req, res, url), res);
 
     // Through writeJsonArray rather than `send`, and through `guard` like every
     // route above it: this is the one answer whose size is the ring's size, and
@@ -408,6 +420,11 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "GET" && url.pathname === "/api/events") {
       return guard(writeJsonArray(res, eventsSince(url.searchParams.get("since") ?? 0)), res);
     }
+    // GET /api/sessions — which sessions this deck is watching and which of
+    // them waits on a human, without the ring itself. See session-summary.mjs.
+    if (req.method === "GET" && url.pathname === "/api/sessions") {
+      return send(res, 200, { ok: true, now: Date.now(), sessions: summarizeSessions(eventsSince(0)) });
+    }
 
     // GET /api/clear — what a POST to this path would do, and to whose log.
     // See handleClearPreview.
@@ -514,7 +531,10 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       void trafficCapture.resume(boundPort).catch(() => {});
       server.once("close", () => trafficCapture.dispose());
       // Codex has no working hooks on Windows — tail its rollout files instead.
-      if (codex) startCodexWatcher(workspace);
+      if (codex) {
+        startCodexWatcher(workspace);
+        server.once("close", stopCodexEnrichment);
+      }
       if (claude) {
         const recovery = createClaudeRecovery({ workspace });
         const recover = () => { void recovery.scan().catch(() => {}); };

package/src/server/installer.mjs

@@ -6,16 +6,21 @@
 // running server still sees both CLIs. Re-runs are safe; entries are tagged
 // with __agent-dag and de-duped.
 import { hookRuntime } from "./app-host.mjs";
-import { readFile, mkdir } from "node:fs/promises";
+import { readFile, mkdir, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { claudeConfigDir } from "./claude-dir.mjs";
+import { claudeCodeVersions, claudeConfigDir, claudeVersionAtLeast } from "./claude-dir.mjs";
+// The first Claude Code that knows StopFailure — see stop-failure.mjs.
+import { STOP_FAILURE, STOP_FAILURE_SINCE } from "./stop-failure.mjs";
 import { CODEX_HOME } from "./codex-dir.mjs";
 import { shellQuoteArg } from "./exec.mjs";
 // The read-before-rewrite and the atomic replace every settings writer goes
 // through — see atomic-write.mjs.
-import { readSettingsForWrite, writeFileAtomic } from "./atomic-write.mjs";
+import { readSettingsForWrite, writeFileAtomic, createTemp, renameWithRetry } from "./atomic-write.mjs";
+// Skill activity's typed-command entry, its opt-in and its version gate — see
+// skill-hook.mjs for why it is not in CLAUDE_EVENTS.
+import { USER_PROMPT_EXPANSION, skillHookDecision } from "./skill-hook.mjs";
 // The discovery dir every deck registers in and every hook reads — see
 // discovery.mjs, which keeps this deck's record there.
 import { AGENT_DAG_DIR } from "./discovery.mjs";
@@ -45,11 +50,46 @@ const CLAUDE_EVENTS = [
   "Notification",
 ];
 
+/**
+ * The events Claude Code added after the ones above, each beside the first
+ * version that knows it — added only where EVERY Claude Code the deck finds on
+ * the machine is at least that version.
+ *
+ * Not an event the older CLI would merely ignore. Until 2.1.101 an event name
+ * Claude Code did not recognise made it ignore the whole settings.json: the
+ * user's permissions, env and hooks, and every one of ours with them (Claude
+ * Code's changelog, 2.1.101). StopFailure arrived in 2.1.78, so a machine still
+ * on anything before that would lose its settings to the entry meant to tell it
+ * more.
+ *
+ * So the version is read off disk (claudeCodeVersions — never a `claude
+ * --version`, which is seconds at boot), and a machine where the deck can find
+ * no version gets none of these: the deck it had before, and a line in the
+ * README saying why. Every boot reinstalls, so a Claude Code updated past the
+ * gate picks the entry up on the deck's next start — and one rolled back below
+ * it has the entry taken back out, the same way.
+ */
+const VERSIONED_CLAUDE_EVENTS = [
+  { event: STOP_FAILURE, since: STOP_FAILURE_SINCE },
+];
+
+/** Which of `versioned` this machine's Claude Code knows: those whose `since`
+ *  every found version is at least, and none when no version was found. */
+function eventsKnownTo(versions, versioned = VERSIONED_CLAUDE_EVENTS) {
+  const found = Array.isArray(versions) ? versions : [];
+  if (found.length === 0) return [];
+  return versioned.filter(v => found.every(ver => claudeVersionAtLeast(ver, v.since))).map(v => v.event);
+}
+
 const PROVIDERS = {
   claude: {
     settingsPath: join(CLAUDE_DIR, "settings.json"),
     hookInstallDir: join(CLAUDE_DIR, "agent-dag"),
     events: CLAUDE_EVENTS,
+    versioned: VERSIONED_CLAUDE_EVENTS,
+    // UserPromptExpansion, for Skill activity (#2181): opt-in, and gated on
+    // every Claude Code found being 2.1.116 or newer (skill-hook.mjs).
+    skillHook: true,
     ensureDir: CLAUDE_DIR,
   },
   // Uninstall-only. Codex hooks do not fire reliably on Windows, so the deck
@@ -336,8 +376,82 @@ async function soundHookRetirement(provider, cfg, current) {
   return { retire, completeSoundHookRetirement };
 }
 
-/** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}. */
-export async function installHooks({ provider = "claude", beforeWrite = null } = {}) {
+/**
+ * Where the settings.json bytes from before the UserPromptExpansion entry was
+ * first added are kept: beside hook.js, in the directory that is ours. Written
+ * once per enabling — the pass that adds the entry where none of ours was —
+ * with mode 0600, because settings.json can hold API keys in its `env`.
+ * `--uninstall` leaves it, as it leaves hook.js: it is the user's own data.
+ */
+export const SKILL_HOOK_BACKUP = "settings.before-skill-hook.json";
+
+/** Whether a group list holds a forwarder of ours. */
+function holdsOurs(groups) {
+  return Array.isArray(groups) && groups.some(isOurEntry);
+}
+
+/** Whether the entry can be added without guessing: `hooks` absent or a plain
+ *  object, and any UserPromptExpansion already there a list. Anything else is
+ *  a file shaped in a way this deck did not write and Claude Code may not read,
+ *  and adding to it is not a decision to take on the user's behalf. */
+function skillHookFits(settings) {
+  const hooks = settings.hooks;
+  if (hooks === undefined) return true;
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) return false;
+  const now = hooks[USER_PROMPT_EXPANSION];
+  return now === undefined || Array.isArray(now);
+}
+
+/** The backup, through a temp file and a rename like every settings write,
+ *  created 0600 and kept 0600. */
+async function writeBackup(path, text) {
+  const { tmp, handle } = await createTemp(path, { mode: 0o600 });
+  try {
+    try {
+      await handle.writeFile(text, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await renameWithRetry(tmp, path);
+  } catch (err) {
+    await unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Whether this pass adds Skill activity's entry: the gate's decision
+ * (skill-hook.mjs), then two refusals of the installer's own — a settings file
+ * whose hooks are not in a shape to add to, and a backup that could not be
+ * written. Either leaves the entry out; neither stops the rest of the install.
+ * `options` is the suite's: skillHookDecision's options, in place of this
+ * machine's environment and disk.
+ */
+async function decideSkillHook(options, settings, before, backupPath) {
+  const decision = await skillHookDecision(options ?? {});
+  if (!decision.install) return decision;
+  if (!skillHookFits(settings)) return { ...decision, install: false, state: "skipped", reason: "settings-shape" };
+  // The bytes the write is about to replace, kept before anything is changed,
+  // the first time the entry goes in. Nothing to keep when there was no file.
+  if (before !== null && !holdsOurs(settings.hooks?.[USER_PROMPT_EXPANSION])) {
+    try {
+      await writeBackup(backupPath, before);
+    } catch {
+      return { ...decision, install: false, state: "skipped", reason: "backup-failed" };
+    }
+    return { ...decision, backup: backupPath };
+  }
+  return decision;
+}
+
+/** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}.
+ *  `claudeVersions` is the suite's: the Claude Code versions to gate the
+ *  versioned events on, in place of the ones on this machine's disk.
+ *  `skillHook` is the suite's too: skillHookDecision's options (the opt-in,
+ *  the installs found, the probe), in place of this machine's. The answer
+ *  carries the decision as `skillHook` for the claude provider. */
+export async function installHooks({ provider = "claude", beforeWrite = null, claudeVersions = null, skillHook = null } = {}) {
   const cfg = PROVIDERS[provider];
   if (!cfg) throw new Error(`unknown provider: ${provider}`);
   // An uninstall-only provider has no event list. Saying so beats the
@@ -357,13 +471,38 @@ export async function installHooks({ provider = "claude", beforeWrite = null } =
   // Discovery dir is shared across providers — always make sure it exists.
   await ensureDir(AGENT_DAG_DIR);
 
+  // Decided before `hooks` is touched, so the shape check sees the file as read.
+  const skill = cfg.skillHook
+    ? await decideSkillHook(skillHook, current, before, join(cfg.hookInstallDir, SKILL_HOOK_BACKUP))
+    : null;
+
   current.hooks = current.hooks ?? {};
 
-  for (const evt of cfg.events) {
+  const versioned = cfg.versioned ?? [];
+  const known = versioned.length ? eventsKnownTo(claudeVersions ?? claudeCodeVersions(), versioned) : [];
+  if (skill?.install) known.push(USER_PROMPT_EXPANSION);
+  // Every event whose entry is ours only while a gate says so.
+  const gated = [...versioned.map(v => v.event), ...(skill ? [USER_PROMPT_EXPANSION] : [])];
+  const events = [...cfg.events, ...known];
+  for (const evt of events) {
     const cleaned = dedupeOurEntries(current.hooks[evt]);
     cleaned.push(buildHookEntry(command));
     current.hooks[evt] = cleaned;
   }
+  // A gated event this machine's Claude Code does not know — or, for Skill
+  // activity's, one nobody asked for — loses our entry, and the key goes with
+  // it when nothing of the user's is left under it: that key is the thing an
+  // older Claude Code cannot read.
+  // A value under that key that is not a list, or a list with nothing of ours
+  // in it, is left exactly as it is: it is not this deck's to delete.
+  for (const event of gated) {
+    const was = current.hooks[event];
+    if (known.includes(event) || !Array.isArray(was)) continue;
+    const cleaned = dedupeOurEntries(was);
+    if (cleaned.length === was.length && cleaned.every((g, i) => g === was[i])) continue;
+    if (cleaned.length === 0) delete current.hooks[event];
+    else current.hooks[event] = cleaned;
+  }
 
   // Retiring the finish-sound hook rides in here, on this read and this write,
   // and this is the seam it needs rather than a convenient one. #704 moved the
@@ -421,8 +560,10 @@ export async function installHooks({ provider = "claude", beforeWrite = null } =
     // and from the park that was its only other copy.
     if (!(await unchangedSince(cfg.settingsPath, before))) {
       return {
-        settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider,
+        settingsPath: cfg.settingsPath, hookPath, events, provider,
         changed: false, raced: true, retire: { ...retire, pending: false },
+        // Nothing was written, so an entry decided on is not on disk.
+        ...(skill ? { skillHook: skill.install ? { ...skill, install: false, state: "skipped", reason: "raced" } : skill } : {}),
       };
     }
     await writeFileAtomic(cfg.settingsPath, next);
@@ -431,7 +572,7 @@ export async function installHooks({ provider = "claude", beforeWrite = null } =
   // is what a live session's cached command still names until the new entry is
   // on disk, and deleting it early turns a stale sound into a missing module.
   if (retire.pending) await completeSoundHookRetirement(retire, current);
-  return { settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider, changed, retire };
+  return { settingsPath: cfg.settingsPath, hookPath, events, provider, changed, retire, ...(skill ? { skillHook: skill } : {}) };
 }
 
 /**

package/src/server/integrations/cache.mjs

@@ -0,0 +1,42 @@
+// A provider client's memory (#2178): the slow, rarely changing reads — a
+// board list, a field map, a server's time-tracking settings — kept for a
+// while. One per client, and the core keeps one client per connection and
+// makes a new one whenever the connection changes (routes.mjs), so nothing
+// cached here outlives the token or the address it was read with.
+
+/** A bounded key/value memory with per-read ages. */
+export function createCache({ max = 500 } = {}) {
+  const entries = new Map();
+  const set = (key, value) => {
+    entries.delete(key);
+    entries.set(key, { at: Date.now(), value });
+    // A bound, not a policy: a provider caching per board per page is still
+    // a few hundred entries.
+    while (entries.size > max) entries.delete(entries.keys().next().value);
+    return value;
+  };
+  const peek = (key, ttlMs) => {
+    const hit = entries.get(key);
+    return hit && Date.now() - hit.at < ttlMs ? hit.value : undefined;
+  };
+  /** Loads in flight, so two panels asking at once share one read. */
+  const pending = new Map();
+  return {
+    /** The value under `key` younger than `ttlMs`, or a fresh one from `load`. */
+    async remember(key, ttlMs, load) {
+      const hit = peek(key, ttlMs);
+      if (hit !== undefined) return hit;
+      if (pending.has(key)) return pending.get(key);
+      const promise = (async () => {
+        try { return set(key, await load()); } finally { pending.delete(key); }
+      })();
+      pending.set(key, promise);
+      return promise;
+    },
+    /** The value under `key` younger than `ttlMs`, or undefined. */
+    peek,
+    set,
+    forget(key) { entries.delete(key); },
+    clear() { entries.clear(); },
+  };
+}

package/src/server/integrations/errors.mjs

@@ -0,0 +1,167 @@
+// What can go wrong between the deck and a tracker it is connected to (#2178),
+// as a short list of kinds the page can act on rather than a status code it
+// would have to interpret.
+//
+// One vocabulary for every provider: Jira today, GitHub and GitLab next. A
+// provider maps its own answers onto these kinds, and the page draws one state
+// per kind — "Jira no longer accepts this token" with a Reconnect, "try again in
+// 30 s", "this server is older than 8.14" — without knowing which tracker said
+// it. The message is ours, written for the person reading the panel; a remote
+// body is never passed through whole, so nothing the tracker echoes (a header, a
+// URL with a query) can ride out on an error.
+import { cooldownFromHeader } from "../quota-oauth.mjs";
+
+/** Every kind an integration error can be, and the status the deck answers
+ *  the page with for it — the contract every provider shares (#2178, #2179):
+ *  401 for a refused or expired token, 403 for an account that may not read
+ *  it, 404 for what is not there, 429 for a rate limit, and 502 for every way
+ *  the tracker itself failed. `invalid` is the deck's own: a form, or a
+ *  parameter, that is not the shape it must be (400). `unavailable` is the
+ *  deck's too: the provider for this kind is not on this deck, or is not
+ *  answering it (503) — nothing is wrong with the connection or the token,
+ *  and a page that does not know the kind reads it as `upstream`. */
+export const ERROR_STATUS = Object.freeze({
+  auth: 401,
+  expired: 401,
+  permission: 403,
+  "not-found": 404,
+  "rate-limit": 429,
+  unreachable: 502,
+  tls: 502,
+  incompatible: 502,
+  upstream: 502,
+  invalid: 400,
+  unavailable: 503,
+});
+
+/** Whether a thrown thing carries one of the kinds — an IntegrationError, or a
+ *  provider's own typed error (#2179's ForgeError) with the same fields. */
+export function isTypedError(err) {
+  return Boolean(err && typeof err === "object" && typeof err.kind === "string" && Object.hasOwn(ERROR_STATUS, err.kind)
+    && typeof err.message === "string");
+}
+
+export class IntegrationError extends Error {
+  /**
+   * @param {keyof typeof ERROR_STATUS} kind
+   * @param {string} message what the panel says, in the deck's own words
+   * @param {{ status?: number, retryAfter?: number, field?: string, detail?: string }} [extra]
+   *   status is the tracker's own HTTP status, when it answered one;
+   *   retryAfter in seconds for a rate limit; field names the form input a bad
+   *   value came from; detail is a short remote reason safe to show (a JQL
+   *   error Jira wrote, never a header or a token)
+   */
+  constructor(kind, message, extra = {}) {
+    super(message);
+    this.name = "IntegrationError";
+    this.kind = Object.hasOwn(ERROR_STATUS, kind) ? kind : "upstream";
+    if (Number.isInteger(extra.status) && extra.status >= 100 && extra.status < 600) this.status = extra.status;
+    if (Number.isFinite(extra.retryAfter)) this.retryAfter = Math.max(1, Math.round(extra.retryAfter));
+    if (typeof extra.field === "string") this.field = extra.field;
+    if (typeof extra.detail === "string" && extra.detail) this.detail = extra.detail.slice(0, 300);
+  }
+}
+
+export function integrationError(kind, message, extra) {
+  return new IntegrationError(kind, message, extra);
+}
+
+/** The JSON body an error is answered with — the one envelope every provider
+ *  answers with: `{ ok: false, error: { kind, message, status?, retryAfter? } }`,
+ *  plus `field` and `detail` when the deck has them. Nothing else of the error
+ *  goes out: not its stack, not a cause, not anything the tracker echoed. */
+export function errorBody(err) {
+  const e = isTypedError(err) ? err : new IntegrationError("upstream", "The deck failed while reading the tracker.");
+  const retryAfter = Number.isFinite(e.retryAfter) ? Math.max(1, Math.round(e.retryAfter)) : null;
+  return {
+    ok: false,
+    error: {
+      kind: e.kind,
+      message: String(e.message).slice(0, 500),
+      ...(Number.isInteger(e.status) ? { status: e.status } : {}),
+      ...(retryAfter ? { retryAfter } : {}),
+      ...(typeof e.field === "string" && e.field ? { field: e.field.slice(0, 40) } : {}),
+      ...(typeof e.detail === "string" && e.detail ? { detail: e.detail.slice(0, 300) } : {}),
+    },
+  };
+}
+
+export function errorStatus(err) {
+  return isTypedError(err) ? ERROR_STATUS[err.kind] : 500;
+}
+
+/** A thrown error as a route answers it, `{ status, body }`: a provider's
+ *  `routes` catches and returns this rather than spelling the envelope. An
+ *  error that carries no kind is a bug of ours, a 500 that says nothing more. */
+export function errorResponse(err) {
+  return { status: errorStatus(err), body: errorBody(err) };
+}
+
+/** Seconds to wait, from a Retry-After header: the deck's own floor and ceiling
+ *  (cooldownFromHeader), because a remote header is not entitled to decide
+ *  either. 30 s when the header is missing or unreadable. */
+export function retryAfterSeconds(raw) {
+  return Math.round(cooldownFromHeader(raw, 30_000, 5_000, 3600_000) / 1000);
+}
+
+/** The node:tls verification codes a fetch through undici surfaces as
+ *  `err.cause.code`. A certificate the deck cannot verify is a `tls` error
+ *  with its own message — there is deliberately no way to ignore one. */
+const TLS_CODES = new Set([
+  "CERT_HAS_EXPIRED", "CERT_NOT_YET_VALID", "CERT_REVOKED", "CERT_UNTRUSTED", "CERT_REJECTED",
+  "DEPTH_ZERO_SELF_SIGNED_CERT", "SELF_SIGNED_CERT_IN_CHAIN", "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "UNABLE_TO_GET_ISSUER_CERT", "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", "ERR_TLS_CERT_ALTNAME_INVALID",
+  "HOSTNAME_MISMATCH", "ERR_SSL_WRONG_VERSION_NUMBER", "EPROTO", "ERR_TLS_HANDSHAKE_TIMEOUT",
+]);
+
+/** A fetch that threw before any answer came back, as an IntegrationError. */
+export function errorFromFetchFailure(err, label = "the tracker") {
+  if (err instanceof IntegrationError) return err;
+  const cause = err?.cause ?? {};
+  const code = String(cause.code ?? err?.code ?? "");
+  if (TLS_CODES.has(code) || /certificate|self[- ]signed|SSL routines|tls/i.test(String(cause.message ?? ""))) {
+    return new IntegrationError("tls",
+      `The deck could not verify ${label}'s HTTPS certificate (${code || "certificate error"}). ` +
+      "Check that the address is right and that the server's certificate is valid for it.");
+  }
+  if (err?.name === "TimeoutError" || err?.name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT") {
+    return new IntegrationError("unreachable", `${capital(label)} did not answer in time.`);
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+    return new IntegrationError("unreachable", `The deck could not find ${label}'s address. Check the URL and your network.`);
+  }
+  return new IntegrationError("unreachable",
+    `The deck could not reach ${label}${code ? ` (${code})` : ""}. Check the URL, your network or VPN.`);
+}
+
+/** An HTTP answer that was not a success, as an IntegrationError. `phase` is
+ *  "validate" while a form is being checked and "use" afterwards: a token
+ *  refused while it is being entered is a wrong token, and refused after it
+ *  has worked is an expired or revoked one. */
+export function errorFromStatus(status, headers, { phase = "use", label = "the tracker", detail } = {}) {
+  const get = name => (typeof headers?.get === "function" ? headers.get(name) : headers?.[name]) ?? null;
+  if (status === 401) {
+    return phase === "validate"
+      ? new IntegrationError("auth", `${capital(label)} did not accept these credentials.`, { status })
+      : new IntegrationError("expired", `${capital(label)} no longer accepts the saved token. It may have expired or been revoked — reconnect with a new one.`, { status });
+  }
+  if (status === 403) {
+    return new IntegrationError("permission", `${capital(label)} refused: the account or token is not allowed to read this.`, { status, detail });
+  }
+  if (status === 429) {
+    const retryAfter = retryAfterSeconds(get("retry-after") ?? get("beta-retry-after"));
+    return new IntegrationError("rate-limit", `${capital(label)} is limiting requests. Try again in ${retryAfter} s.`, { status, retryAfter });
+  }
+  if (status === 404) return new IntegrationError("not-found", `${capital(label)} has no such page or record, or this account cannot see it.`, { status, detail });
+  if (status === 400) return new IntegrationError("upstream", `${capital(label)} refused the request.`, { status, detail });
+  if (status === 502 || status === 503 || status === 504) {
+    const wait = get("retry-after");
+    return new IntegrationError("unreachable", `${capital(label)} is not answering right now (${status}). Try again shortly.`,
+      { status, ...(wait ? { retryAfter: retryAfterSeconds(wait) } : {}) });
+  }
+  return new IntegrationError("upstream", `${capital(label)} answered ${status}.`, { status, detail });
+}
+
+function capital(text) {
+  return text ? text[0].toUpperCase() + text.slice(1) : text;
+}

package/src/server/integrations/forge.mjs

@@ -0,0 +1,76 @@
+// The GitHub and GitLab providers (#2179), for the integrations core's table;
+// registry.mjs has the contract.
+//
+// Both are the same shape: a client from github-api.mjs or gitlab-api.mjs made
+// for one connection — which reads, keeps its short caches, and fetches the
+// images the panel draws — and the reads in forge-routes.mjs under
+// /api/integrations/<kind>/<connId>/. What differs is where the forge is:
+// GitHub is github.com (an Enterprise Server address can come later; the
+// client already takes one), GitLab is gitlab.com or the instance the user
+// typed, under its path if it has one.
+import { ForgeError } from "../forge-http.mjs";
+import { forgeRead } from "../forge-routes.mjs";
+import { createGithubClient } from "../github-api.mjs";
+import { createGitlabClient } from "../gitlab-api.mjs";
+import { integrationError } from "./errors.mjs";
+import { normaliseBaseUrl } from "./proxy.mjs";
+
+const GITHUB = "https://github.com";
+const GITLAB = "https://gitlab.com";
+
+/** The token typed, or the saved one when an edit left the field blank. */
+function tokenFrom(input, existing) {
+  const typed = typeof input?.token === "string" ? input.token.trim() : "";
+  const secret = typed || existing?.secret || null;
+  if (!secret) throw integrationError("invalid", "Enter a token.", { field: "token" });
+  return secret;
+}
+
+/** The client, with validate() in the core's terms: a token refused while a
+ *  form is checked is a wrong one (auth); refused on Test, after it was
+ *  saved, it has expired or been revoked. */
+function withPhase(client) {
+  return {
+    ...client,
+    async validate({ phase = "validate" } = {}) {
+      try {
+        return await client.validate();
+      } catch (err) {
+        if (phase === "use" && err?.kind === "auth") throw new ForgeError("expired", err.message, { status: err.status });
+        throw err;
+      }
+    },
+  };
+}
+
+const reads = (client, method, subpath, params) => forgeRead(client, method, subpath, params);
+
+export const githubProvider = {
+  kind: "github",
+  label: "GitHub",
+  createClient: (conn, secret, { fetchImpl } = {}) =>
+    withPhase(createGithubClient({ baseUrl: conn.baseUrl || GITHUB, token: secret, fetchImpl })),
+  routes: reads,
+  parseInput: (input, existing) => ({ baseUrl: GITHUB, secret: tokenFrom(input, existing), meta: {} }),
+  // Two GitHub connections are two accounts; the login tells them apart.
+  defaultName: checked => checked?.account?.login || "GitHub",
+};
+
+export const gitlabProvider = {
+  kind: "gitlab",
+  label: "GitLab",
+  createClient: (conn, secret, { fetchImpl } = {}) =>
+    withPhase(createGitlabClient({ baseUrl: conn.baseUrl || GITLAB, token: secret, fetchImpl })),
+  routes: reads,
+  parseInput: (input, existing) => ({
+    baseUrl: input?.where === "self"
+      ? normaliseBaseUrl(input?.baseUrl, { field: "baseUrl", label: "your GitLab's address" })
+      : GITLAB,
+    secret: tokenFrom(input, existing),
+    meta: {},
+  }),
+  // Two GitLab connections are usually two instances; the host tells them apart.
+  defaultName: checked => {
+    try { return new URL(checked.baseUrl).host; } catch { return "GitLab"; }
+  },
+};