@ctrl-spc/cs 0.5.0 → 0.7.0

package/dist/env.js

@@ -10,6 +10,48 @@ export const SUPABASE_KEY = process.env.CTRL_SPC_SUPABASE_KEY || 'sb_publishable
 export const HEARTBEAT_INTERVAL_MS = 10_000;
 /** Command (ping) poll cadence. */
 export const COMMAND_POLL_INTERVAL_MS = 3_000;
+/** Orchestrator listener cadence (feature 16, Slice 3). The interval a designated
+ *  machine waits before looking for a new loose todo — and therefore the worst
+ *  case for ux.md mock state E step 1, "Working with no agent named. Present for
+ *  at most one poll interval". Matched to the command poll: both are one small
+ *  indexed read against the user's own rows, and a second cadence to reason
+ *  about would buy nothing. Not faster — the panel is realtime, so the user sees
+ *  their own todo appear instantly; this interval only bounds how long before an
+ *  agent is NAMED on it. */
+export const ORCHESTRATOR_POLL_INTERVAL_MS = 3_000;
+/** !Cleanup Phase 7 Slice 1 (I21, I24) — HOW MANY AGENTS MAY RUN AT ONCE.
+ *
+ *  Was structurally ONE (a boolean `busy` on the listener state), which is the
+ *  defect behind the user's first requirement: a second request typed seconds
+ *  after the first sat untouched until the first finished, for up to the whole
+ *  spawn timeout.
+ *
+ *  THREE, and bounded on purpose. Each run is a real headless `claude` process
+ *  with real memory and real API cost, so a burst of twenty requests must not
+ *  fork twenty agents. Three is enough that a question is never stuck behind a
+ *  build — the case the user named — while staying comfortable on a laptop that
+ *  is also running the user's editor and browser.
+ *
+ *  Overridable per machine, because the right number on a 64 GB desktop is not
+ *  the right number on a laptop.
+ *
+ *  THE REAL CEILING TURNED OUT NOT TO BE THE MACHINE. The Phase 7 Slice 1 walk
+ *  ran three concurrent Opus workers and two of them came back `claude exited 1`
+ *  while the third answered normally — the agent binary was fine when run by
+ *  hand, and the stream carried a `rate_limit_event` for the five-hour window.
+ *  So the binding constraint on concurrency is the user's API rate limit, not
+ *  RAM or CPU, and raising this number past what the account allows converts
+ *  work that would have queued into work that FAILS and burns attempts. A
+ *  rate-limited run is currently indistinguishable from a crashed one, which is
+ *  worth fixing before this default goes any higher. */
+export const ORCHESTRATOR_MAX_CONCURRENT = Number(process.env.CTRL_SPC_V2_MAX_CONCURRENT) || 3;
+/** Hard ceiling on one headless agent run before it is killed and the todo is
+ *  released for retry. Generous on purpose: the spawned agent does REAL WORK
+ *  (ux.md § Purpose) — it may cut a worktree, run a build, read a codebase — so a
+ *  short timeout would kill legitimate work and hand the user a released todo
+ *  that keeps failing the same way. It exists only so a wedged process cannot
+ *  hold the single in-flight slot forever. */
+export const ORCHESTRATOR_SPAWN_TIMEOUT_MS = 30 * 60_000;
 /** How long a work session stays "working" after the agent's last ctrl-spc tool
  *  call, with no further activity. The companion keeps last_seen_at fresh within
  *  this window; once it lapses (agent finished, Ctrl-C'd, crashed, or asleep) the

package/dist/failure-reason.js

@@ -0,0 +1,98 @@
+/**
+ * 18a SLICE 5: WHAT THE USER READS WHEN AN ATTEMPT FAILS.
+ *
+ * .implementations/18-orchestrator/18a-you-answer-and-the-work-continues/ux.md
+ *   § "Slice 5. A failure you did not cause reads like the machine"
+ *
+ * The daemon's internal error strings are exit statuses: `claude exited 1`,
+ * `claude exited ENOENT`, `codex produced no output`. They are the right thing
+ * to LOG, and they are what every existing test asserts on, so they are left
+ * exactly as they are. What was wrong is that the same string reached the card.
+ *
+ * An exit code is not an explanation. It is identical whether the binary is
+ * missing, the account is rate limited, or the agent genuinely crashed, and the
+ * user cannot act on any of them from the number. This translates at the point
+ * the reason is STORED, so the log keeps the diagnosis and the card gets the
+ * sentence.
+ *
+ * THE FALLBACK IS HONEST, not a guess. An error this does not recognise becomes
+ * "the agent stopped without finishing", which is true of every one of them, and
+ * the technical string is still in the daemon log for whoever needs it. Inventing
+ * a cause from an exit code would be the same defect wearing better words.
+ */
+/** How many times the orchestrator dispatches before giving up.
+ *  `MAX_ATTEMPTS` in orchestrator.ts is the definition; this module does not
+ *  need it, but the web app's copy of the number is documented against the same
+ *  fact: it is deliberately not configurable, so a constant cannot drift into a
+ *  lie the way a configurable one would. */
+/**
+ * The agent's name as the user picked it in the machine popover.
+ *
+ * Shared rather than inlined because 18a Slice 7 composes its own sentence: the
+ * liveness watch does not have an error string to translate, it has a FACT (the
+ * process is gone), and a sentence written from that fact is more honest than
+ * one matched out of a string nobody wrote.
+ *
+ * An agent this does not know about is passed through rather than mangled.
+ */
+export function agentDisplayName(agent) {
+    return agent === 'claude' ? 'Claude' : agent === 'codex' ? 'Codex' : agent;
+}
+/**
+ * Plain words for a failed attempt, from the daemon's own error string plus
+ * whatever the child printed to stderr.
+ *
+ * `agent` is capitalised into the sentence because the user picked it by name
+ * ("Claude", "Codex") and a sentence about "the agent" reads as being about
+ * something they did not choose.
+ */
+export function plainFailureReason(agent, error, stderr = '') {
+    const name = agentDisplayName(agent);
+    const haystack = `${error}\n${stderr}`.toLowerCase();
+    /* THE COMMAND IS NOT THERE. `ENOENT` from spawn is the fixture the scenario
+       uses (the agent removed from PATH) and the single most likely real cause on
+       a fresh machine. It is also the one the user can fix in a minute, which is
+       why it is worth naming rather than folding into the fallback. */
+    if (haystack.includes('enoent') || haystack.includes('command not found')) {
+        return `${name} is not installed on this machine, or is not on its PATH.`;
+    }
+    /* RATE LIMITED. ux.md records the measurement this came from: on 2026-08-07
+       two of three concurrent runs died on the account's rate limit while the same
+       work succeeded alone. It is the reason the cap stays at three, and until now
+       it was indistinguishable from a crash. */
+    if (haystack.includes('rate limit') || haystack.includes('rate_limit')
+        || haystack.includes('429') || haystack.includes('overloaded')) {
+        return `${name}'s usage limit is in effect on this account, so the run could not start.`;
+    }
+    /* SIGNED OUT. Recoverable by the user, and silent otherwise: the run just
+       fails, over and over, for as long as the session is stale.
+  
+       18a SLICE 7 ADDED THE OAUTH AND 401 SIGNATURES, from the real thing rather
+       than from imagination. The Windows machine's Claude Code had a stale token
+       and said, on STDOUT as a stream-json result: `"error":
+       "authentication_failed"` and `API Error: 401 OAuth access token has
+       expired.` The word "authentication" above would have matched that, but only
+       once stdout was being read at all, which is the other half of the fix. `401`
+       and `oauth` are here so the same failure is caught when it arrives in
+       shorter words. */
+    if (haystack.includes('unauthorized') || haystack.includes('not logged in')
+        || haystack.includes('authentication') || haystack.includes('oauth')
+        || haystack.includes('401')) {
+        return `${name} is not signed in on this machine.`;
+    }
+    /* THE RUN WAS KILLED, by the timeout or by a signal from outside. Not the
+       user's Stop, which never reaches here: a stopped run is settled with its own
+       flag well before this. */
+    if (haystack.includes('timed out')) {
+        return `The run was stopped for taking too long.`;
+    }
+    if (haystack.includes('killed by')) {
+        return `${name} was killed on this machine before it finished.`;
+    }
+    /* IT RAN AND SAID NOTHING. A clean exit with no answer, which is a real state
+       and reads very differently from a crash. */
+    if (haystack.includes('produced no output')) {
+        return `${name} finished without producing an answer.`;
+    }
+    return `${name} stopped without finishing.`;
+}

package/dist/index.js

@@ -11,7 +11,7 @@ const HELP = `cs — CTRL+SPC
   cs                Open the Companion app (the front door)
   cs open           Open the Companion app in your browser
   cs login          Sign in from the terminal and link this computer
-  cs start          Come online now, no window (used by auto-start)
+  cs start          Come online and answer cards, no window (used by auto-start)
   cs status         Show sign-in state, computer, and detected agents
   cs autostart on   Come online automatically at login
   cs autostart off  Stop coming online at login