@herdingchats/friday 0.1.567 → 0.1.569

package/herd.mjs

@@ -18,7 +18,7 @@ var __export = (target, all) => {
 var define_HERD_PACKAGE_default;
 var init_define_HERD_PACKAGE = __esm({
   "<define:HERD_PACKAGE>"() {
-    define_HERD_PACKAGE_default = { version: "0.1.567", gitHead: "816afa2c448b0a5330ddece39cdb0567ef65a3c5" };
+    define_HERD_PACKAGE_default = { version: "0.1.569", gitHead: "ac28f0e97b92fbe2178387595a511d35c3ae4953" };
   }
 });
 
@@ -1319,6 +1319,19 @@ var init_events = __esm({
       }),
       event("terminal.exited", { terminalId: nonEmpty6, exitCode: z12.number().int().nullable() }),
       event("terminal.notice_failed", { terminalId: nonEmpty6, reason: nonEmpty6 }),
+      /**
+       * The agent's start didn't check in with `herd inbox` within its window, so it looks like it
+       * needs someone at its terminal. `agent` is its CLI's name, and `detail` what the screen showed,
+       * when herd recognized it.
+       */
+      event("terminal.needs_attention", {
+        terminalId: nonEmpty6,
+        agent: nonEmpty6,
+        machineName: nonEmpty6,
+        detail: z12.string().max(200).optional()
+      }),
+      /** A start that needed attention checked in after all. */
+      event("terminal.checked_in", { terminalId: nonEmpty6 }),
       /** The daemon closed one of Claude Code's own dialogs that it has recorded, named by its title. */
       event("terminal.dialog_closed", { terminalId: nonEmpty6, dialog: nonEmpty6 }),
       // A subscribed event that didn't wake the conversation, with the reason. One that woke it is a
@@ -1466,6 +1479,9 @@ var init_conversation_state = __esm({
       "author_not_linked",
       // The only agents that could take it showed their own sign-in, so a person has to sign in.
       "agent_signed_out",
+      // Its agent started and never checked in with `herd inbox`, so it looks like it needs someone
+      // at its terminal.
+      "agent_needs_attention",
       // The only machines that could take it have a folder that isn't there, such as a drive not
       // yet mounted.
       "folder_unavailable",
@@ -1568,6 +1584,7 @@ var init_conversation_state = __esm({
       author_not_linked: "the author's account isn't linked",
       delegate_waiting: "a delegate is waiting on someone",
       agent_signed_out: "its agent isn't signed in on its machine",
+      agent_needs_attention: "its agent looks like it needs someone at its terminal",
       folder_unavailable: "its machine's folder isn't there",
       no_suitable_worker: "no worker may take it under its configuration",
       notice_failed: "a notice didn't reach the agent's terminal",
@@ -4473,6 +4490,8 @@ var localRequestSchema = z19.object({
     "repo",
     "activate"
   ]),
+  // The key of the agent's start, from `HERD_START`, which `herd inbox` proves the start with.
+  start: z19.string().min(1).max(100).optional(),
   // `herd repo`: the repo it added to the conversation's folder, for the daemon to record.
   repo: z19.object({
     remote: z19.string().min(1).max(500),
@@ -4821,6 +4840,50 @@ async function permissionHook(raw, options = {}) {
   }
 }
 
+// src/timing.ts
+init_define_HERD_PACKAGE();
+var CHECK_IN_MS = 15e3;
+var VARIABLES = {
+  settleMs: "HERD_SETTLE_MS",
+  pollMs: "HERD_POLL_MS",
+  confirmMs: "HERD_CONFIRM_MS",
+  pasteMs: "HERD_PASTE_MS",
+  renewMs: "HERD_RENEW_MS",
+  hookSettleMs: "HERD_HOOK_SETTLE_MS",
+  agyIdleSettleMs: "HERD_AGY_IDLE_SETTLE_MS",
+  promptPollMs: "HERD_PROMPT_POLL_MS",
+  noticeRetryMs: "HERD_NOTICE_RETRY_MS",
+  investigateAfterMs: "HERD_INVESTIGATE_AFTER_MS",
+  idleMs: "HERD_IDLE_MS",
+  watchMs: "HERD_WATCH_MS",
+  usageReportMs: "HERD_USAGE_REPORT_MS",
+  usageStaleMs: "HERD_USAGE_STALE_MS",
+  activationMs: "HERD_ACTIVATION_MS",
+  activationPollMs: "HERD_ACTIVATION_POLL_MS",
+  signInRestartMs: "HERD_SIGN_IN_RESTART_MS",
+  checkInMs: "HERD_CHECK_IN_MS",
+  machineCheckMs: "HERD_MACHINE_CHECK_MS"
+};
+function timingFromEnv(env) {
+  const timing = {};
+  for (const [key, name] of Object.entries(VARIABLES)) {
+    const raw = env[name];
+    if (raw === void 0 || raw === "") continue;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0) {
+      throw new HerdError(`${name} must be a number of milliseconds, not "${raw}".`);
+    }
+    timing[key] = value;
+  }
+  return timing;
+}
+function driverTiming(timing) {
+  const { settleMs, pollMs, confirmMs } = timing;
+  return Object.fromEntries(
+    Object.entries({ settleMs, pollMs, confirmMs }).filter(([, value]) => value !== void 0)
+  );
+}
+
 // src/activation.ts
 var ACTIVATION_DEADLINE_MS = 3 * 60 * 1e3;
 var ACTIVATION_POLL_MS = 500;
@@ -5027,6 +5090,7 @@ var Activator = class {
     const { agent } = current;
     const deadline = Date.now() + (this.options.deadlineMs ?? ACTIVATION_DEADLINE_MS);
     const restartMs = this.options.signInRestartMs ?? SIGN_IN_RESTART_MS;
+    const checkInMs = this.options.checkInMs ?? CHECK_IN_MS;
     const pollMs = this.options.pollMs ?? ACTIVATION_POLL_MS;
     let seen = "didnt_start";
     let startedAt = 0;
@@ -5061,7 +5125,7 @@ var Activator = class {
     await start();
     while (!current.checkedIn && Date.now() < deadline && !this.stopped) {
       const reading = await driver.read(current.terminal).catch(() => null);
-      if (reading?.state === "signed_out") {
+      if (reading?.state === "signed_out" && Date.now() - startedAt >= checkInMs) {
         seen = "signed_out";
         if (!signingIn) {
           signingIn = true;
@@ -6616,6 +6680,10 @@ init_define_HERD_PACKAGE();
 // src/commands/terminal.ts
 init_define_HERD_PACKAGE();
 var DAEMON_WAIT_MS = Number(process.env.HERD_DAEMON_WAIT_MS ?? 3e4);
+function withStart(request) {
+  const start = process.env.HERD_START;
+  return start ? { start, ...request } : request;
+}
 async function fromTerminal(request) {
   const socket = process.env.HERD_SOCKET;
   const secret = process.env.HERD_TERMINAL;
@@ -6625,7 +6693,7 @@ async function fromTerminal(request) {
   let reply = null;
   const deadline = Date.now() + DAEMON_WAIT_MS;
   while (!reply) {
-    reply = await askDaemon(socket, { secret, ...request }).catch(() => null);
+    reply = await askDaemon(socket, { secret, ...withStart(request) }).catch(() => null);
     if (reply) break;
     if (Date.now() > deadline) throw new HerdError("Couldn't reach herd's daemon. Is it running?");
     await new Promise((resolve7) => setTimeout(resolve7, 500));
@@ -7448,6 +7516,9 @@ var ownPrompt = (draft) => OWN_PROMPTS.find(
 ) ?? (draft.startsWith(DELEGATE_START) || draft.length >= 40 && DELEGATE_START.startsWith(draft) ? draft : null);
 var SESSION_ID = /^[A-Za-z0-9-]{1,100}$/;
 var SUBMIT_RETRIES = 3;
+function withStartKey(command, startKey) {
+  return startKey ? `HERD_START=${startKey} ${command}` : command;
+}
 var DEFAULT_TIMING = { settleMs: 800, pollMs: 150, startMs: 6e4, confirmMs: 3e3 };
 var sleep3 = (ms) => new Promise((resolve7) => setTimeout(resolve7, ms));
 var EXIT_WAIT_MS = 5e3;
@@ -7504,12 +7575,12 @@ var AgentDriver = class {
    * `claude --resume <id>`. Resuming without an ID types `/resume` and picks the newest
    * conversation, which is this worktree's only agent.
    */
-  async start(name, cwd, { resume = false, sessionId = null, ownFolder: ownFolder2 } = {}) {
+  async start(name, cwd, { resume = false, sessionId = null, ownFolder: ownFolder2, startKey = null } = {}) {
     const known = sessionId !== null && SESSION_ID.test(sessionId);
     const byId = resume && known;
     const command = byId ? `claude --resume ${sessionId}` : !resume && known ? `claude --session-id ${sessionId}` : "claude";
     await this.settle(name);
-    await this.terminals.type(name, command);
+    await this.terminals.type(name, withStartKey(command, startKey));
     await this.terminals.press(name, "enter");
     const first = await this.until(
       name,
@@ -7802,11 +7873,11 @@ var AgyDriver = class {
    * waits for its prompt box. It trusts the folder only in a worktree the daemon made. agy chooses
    * a session's ID itself, and its `SessionStart` hook reports it.
    */
-  async start(name, cwd, { resume = false, sessionId = null, ownFolder: ownFolder2 } = {}) {
+  async start(name, cwd, { resume = false, sessionId = null, ownFolder: ownFolder2, startKey = null } = {}) {
     const byId = resume && sessionId !== null && SESSION_ID.test(sessionId);
     const command = byId ? `agy --conversation=${sessionId} ${AGY_FLAGS}` : `agy ${AGY_FLAGS}`;
     await this.settle(name);
-    await this.terminals.type(name, command);
+    await this.terminals.type(name, withStartKey(command, startKey));
     await this.terminals.press(name, "enter");
     const first = await this.until(
       name,
@@ -8793,11 +8864,11 @@ var CodexDriver = class {
    * Types `codex` into the settled shell, or `codex resume <id>` to continue a session, and waits
    * for its composer. Codex chooses a session's ID itself, when it takes the first prompt.
    */
-  async start(name, cwd, { resume = false, sessionId = null, ownFolder: ownFolder2 } = {}) {
+  async start(name, cwd, { resume = false, sessionId = null, ownFolder: ownFolder2, startKey = null } = {}) {
     const byId = resume && sessionId !== null && SESSION_ID.test(sessionId);
     const command = byId ? `codex resume ${sessionId} ${CODEX_FLAGS}` : `codex ${CODEX_FLAGS}`;
     await this.settle(name);
-    await this.terminals.type(name, command);
+    await this.terminals.type(name, withStartKey(command, startKey));
     await this.terminals.press(name, "enter");
     const first = await this.until(
       name,
@@ -9853,48 +9924,6 @@ var HostTerminals = class {
   }
 };
 
-// src/timing.ts
-init_define_HERD_PACKAGE();
-var VARIABLES = {
-  settleMs: "HERD_SETTLE_MS",
-  pollMs: "HERD_POLL_MS",
-  confirmMs: "HERD_CONFIRM_MS",
-  pasteMs: "HERD_PASTE_MS",
-  renewMs: "HERD_RENEW_MS",
-  hookSettleMs: "HERD_HOOK_SETTLE_MS",
-  agyIdleSettleMs: "HERD_AGY_IDLE_SETTLE_MS",
-  promptPollMs: "HERD_PROMPT_POLL_MS",
-  noticeRetryMs: "HERD_NOTICE_RETRY_MS",
-  investigateAfterMs: "HERD_INVESTIGATE_AFTER_MS",
-  idleMs: "HERD_IDLE_MS",
-  watchMs: "HERD_WATCH_MS",
-  usageReportMs: "HERD_USAGE_REPORT_MS",
-  usageStaleMs: "HERD_USAGE_STALE_MS",
-  activationMs: "HERD_ACTIVATION_MS",
-  activationPollMs: "HERD_ACTIVATION_POLL_MS",
-  signInRestartMs: "HERD_SIGN_IN_RESTART_MS",
-  machineCheckMs: "HERD_MACHINE_CHECK_MS"
-};
-function timingFromEnv(env) {
-  const timing = {};
-  for (const [key, name] of Object.entries(VARIABLES)) {
-    const raw = env[name];
-    if (raw === void 0 || raw === "") continue;
-    const value = Number(raw);
-    if (!Number.isFinite(value) || value < 0) {
-      throw new HerdError(`${name} must be a number of milliseconds, not "${raw}".`);
-    }
-    timing[key] = value;
-  }
-  return timing;
-}
-function driverTiming(timing) {
-  const { settleMs, pollMs, confirmMs } = timing;
-  return Object.fromEntries(
-    Object.entries({ settleMs, pollMs, confirmMs }).filter(([, value]) => value !== void 0)
-  );
-}
-
 // src/usage-reporter.ts
 init_define_HERD_PACKAGE();
 var USAGE_REPORT_MS = 5 * 60 * 1e3;
@@ -10159,6 +10188,17 @@ var workspaceFields = z25.object({
   codexOffset: z25.number().default(0),
   /** When the agent was last started, so Codex's new session file is told from older ones. */
   agentStartedAt: z25.number().default(0),
+  /**
+   * The key the agent was last started with, as `HERD_START`. Its `herd inbox` carrying this key
+   * is what proves the start works: never a hook, a prompt being taken, or the screen.
+   */
+  startKey: z25.string().nullable().default(null),
+  /** Whether the current start has checked in. One from before keys counts as proven. */
+  startProven: z25.boolean().default(true),
+  /** When the check-in window of an unproven start began, or null once it's proven or for none. */
+  checkInFrom: z25.number().nullable().default(null),
+  /** Whether this start has been flagged as needing someone at its terminal, so it's said once. */
+  needsAttention: z25.boolean().default(false),
   /** What agy's status line last said its agent was doing, and when. */
   agentState: z25.enum(["working", "idle"]).nullable().default(null),
   agentStateAt: z25.number().default(0)
@@ -10235,7 +10275,7 @@ async function claimChange(ws, workspace, change) {
 
 // src/workspaces/delivery.ts
 init_define_HERD_PACKAGE();
-import { randomUUID as randomUUID6 } from "node:crypto";
+import { randomBytes as randomBytes6, randomUUID as randomUUID6 } from "node:crypto";
 import { join as join30 } from "node:path";
 
 // src/workspaces/repos.ts
@@ -10535,6 +10575,10 @@ async function setUp(ws, conversationId) {
     codexFile: null,
     codexOffset: 0,
     agentStartedAt: 0,
+    startKey: null,
+    startProven: true,
+    checkInFrom: null,
+    needsAttention: false,
     agentState: null,
     agentStateAt: 0
   };
@@ -10578,6 +10622,12 @@ async function openLead(ws, workspace) {
   });
 }
 
+// src/workspaces/watch.ts
+init_define_HERD_PACKAGE();
+
+// src/workspaces/check-in.ts
+init_define_HERD_PACKAGE();
+
 // src/workspaces/signed-out.ts
 init_define_HERD_PACKAGE();
 init_src();
@@ -10598,14 +10648,50 @@ async function releaseSignedOut(ws, workspace) {
     terminalNotice: false,
     idleSince: null,
     noticeFailedAt: null,
-    noticeFailure: null
+    noticeFailure: null,
+    checkInFrom: null,
+    needsAttention: false
   });
   if (workspace.status !== "exited") await ws.report(id2, "exited");
   await ws.post(`${ws.conversationPath(id2)}/release`, { reason: "agent_signed_out" });
 }
 
-// src/workspaces/watch.ts
-init_define_HERD_PACKAGE();
+// src/workspaces/check-in.ts
+async function checkIn(ws, workspace, grant, start) {
+  if (workspace.startProven || !start || start !== workspace.startKey) return;
+  if (grant.terminalId !== workspace.lead) return;
+  const id2 = workspace.conversationId;
+  ws.update(id2, { startProven: true, checkInFrom: null, needsAttention: false });
+  if (!workspace.needsAttention) return;
+  ws.log(`${id2}: the agent checked in after all.`);
+  await ws.terminalEvent(id2, {
+    type: "terminal.checked_in",
+    payload: { terminalId: workspace.lead }
+  });
+}
+function checkInOverdue(ws, workspace, now = Date.now()) {
+  return !workspace.startProven && workspace.checkInFrom !== null && now - workspace.checkInFrom >= (ws.options.checkInMs ?? CHECK_IN_MS);
+}
+async function followCheckIn(ws, workspace, reading) {
+  if (!checkInOverdue(ws, workspace)) return false;
+  if (reading?.state === "signed_out") {
+    await releaseSignedOut(ws, workspace);
+    return true;
+  }
+  if (workspace.needsAttention) return false;
+  const id2 = workspace.conversationId;
+  ws.update(id2, { needsAttention: true });
+  ws.log(`${id2}: ${workspace.agent} started but didn't check in, so it needs someone.`);
+  await ws.terminalEvent(id2, {
+    type: "terminal.needs_attention",
+    payload: {
+      terminalId: workspace.lead,
+      agent: workspace.agent,
+      machineName: ws.options.machineName()
+    }
+  });
+  return false;
+}
 
 // src/workspaces/investigation.ts
 init_define_HERD_PACKAGE();
@@ -10613,11 +10699,19 @@ import { randomUUID as randomUUID5 } from "node:crypto";
 import { appendFileSync as appendFileSync3, mkdirSync as mkdirSync21 } from "node:fs";
 import { join as join29 } from "node:path";
 function needsInvestigator(ws, workspace, reading) {
+  const allowed = ws.options.canInvestigate ? ws.options.canInvestigate() : workspace.agent === "claude-code";
+  if (!allowed || !reading || workspace.investigation) return false;
+  if (reading.state !== "unknown" || reading.knownDialog || reading.program === "shell") {
+    return false;
+  }
+  const trigger = investigationTrigger(ws, workspace);
+  return trigger !== null && workspace.investigatedFailure !== trigger;
+}
+function investigationTrigger(ws, workspace) {
+  if (workspace.needsAttention && checkInOverdue(ws, workspace)) return workspace.checkInFrom;
   const failedAt = workspace.noticeFailedAt;
-  if (workspace.agent === "codex" || workspace.agent === "agy") return false;
-  return Boolean(
-    reading && failedAt !== null && workspace.deferred && !workspace.investigation && workspace.investigatedFailure !== failedAt && Date.now() - failedAt >= (ws.options.investigateAfterMs ?? INVESTIGATE_AFTER_MS) && reading.state === "unknown" && !reading.knownDialog && reading.program !== "shell"
-  );
+  const after = ws.options.investigateAfterMs ?? INVESTIGATE_AFTER_MS;
+  return failedAt !== null && workspace.deferred && Date.now() - failedAt >= after ? failedAt : null;
 }
 async function openInvestigator(ws, workspace) {
   const id2 = workspace.conversationId;
@@ -10627,10 +10721,11 @@ async function openInvestigator(ws, workspace) {
   );
   const secret = ws.options.local().grant({ terminalId: terminal, conversationId: id2, investigates: workspace.lead });
   ws.update(id2, {
-    investigatedFailure: workspace.noticeFailedAt,
+    investigatedFailure: investigationTrigger(ws, workspace),
     investigation: { terminal, secret, startedAt: Date.now(), screen, key: null, promptId: null }
   });
   ws.log(`${id2}: opened an investigator for a screen herd can't read.`);
+  if (workspace.agent !== "claude-code") configureClaude(ws, workspace);
   const shell = ws.options.shell ?? process.env.SHELL ?? "/bin/sh";
   try {
     await ws.options.terminals.create({
@@ -10801,7 +10896,8 @@ async function watchOne(ws, conversationId, terminals, rows = []) {
     lead = (await ws.options.terminals.list()).find((t) => t.name === workspace?.lead);
   }
   let reading = lead && !lead.exited ? await ws.driverFor(workspace).read(workspace.lead) : null;
-  if (reading?.state === "signed_out") return releaseSignedOut(ws, workspace);
+  if (await followCheckIn(ws, workspace, reading)) return;
+  workspace = ws.get(conversationId) ?? workspace;
   if (reading && !reading.knownDialog && workspace.closedDialog) {
     workspace = ws.update(conversationId, { closedDialog: null });
   }
@@ -10983,11 +11079,18 @@ async function deliver(ws, conversationId, delivery) {
       });
     }
     const resume = workspace.started && (!ownId || workspace.sessionId !== null);
-    workspace = ws.update(conversationId, { agentStartedAt: Date.now() });
+    workspace = ws.update(conversationId, {
+      agentStartedAt: Date.now(),
+      startKey: randomBytes6(12).toString("hex"),
+      startProven: false,
+      checkInFrom: null,
+      needsAttention: false
+    });
     await ws.driverFor(workspace).start(workspace.lead, workspace.folder, {
       resume,
       sessionId: workspace.sessionId,
-      ownFolder: isHerdFolder(workspace.folder, rootOf(ws))
+      ownFolder: isHerdFolder(workspace.folder, rootOf(ws)),
+      startKey: workspace.startKey
     });
     workspace = ws.update(conversationId, {
       started: true,
@@ -10996,16 +11099,15 @@ async function deliver(ws, conversationId, delivery) {
       askedToReply: false,
       handledThisTurn: false
     });
-    if ((await ws.driverFor(workspace).read(workspace.lead)).state === "signed_out") {
-      return releaseSignedOut(ws, workspace);
-    }
     if (!await claim(ws, workspace)) return;
     const result2 = await submitKeepingClaim(
       ws,
       conversationId,
       workspace.readSeq === 0 ? workspace.parent ? delegatePrompt(workspace.parent) : STARTING_PROMPT : NOTICE
     );
-    return afterSubmit(ws, ws.get(conversationId) ?? workspace, result2);
+    workspace = ws.get(conversationId) ?? workspace;
+    if (!workspace.startProven) workspace = ws.update(conversationId, { checkInFrom: Date.now() });
+    return afterSubmit(ws, workspace, result2);
   }
   let reading = await ws.driverFor(workspace).read(workspace.lead);
   if (reading.knownDialog) {
@@ -11396,7 +11498,10 @@ async function answer(ws, grant, request, gone = new AbortController().signal) {
   if (request.op === "activate") {
     return { ok: false, error: "Only an agent's activation terminal can check in." };
   }
-  if (request.op === "inbox") return inbox(ws, workspace);
+  if (request.op === "inbox") {
+    await checkIn(ws, workspace, grant, request.start);
+    return inbox(ws, ws.get(grant.conversationId) ?? workspace);
+  }
   if (request.op === "send") return send(ws, workspace, request);
   if (request.op === "channels") return channels(ws, workspace);
   if (request.op === "watch") return watch(ws, workspace, request);
@@ -12687,6 +12792,11 @@ async function runDaemon(args) {
     activations: {
       fromTerminal: async (grant, request) => activator?.fromTerminal(grant, request) ?? { ok: false, error: "This activation is over." }
     },
+    // The investigator is Claude Code, so any agent's stuck screen gets one where it's activated.
+    canInvestigate: () => Boolean(
+      daemon?.chosenClis().some((cli) => cli.name === "claude-code") && activator?.states()["claude-code"]?.state === "activated"
+    ),
+    ...timing.checkInMs === void 0 ? {} : { checkInMs: timing.checkInMs },
     // The agent stops being offered before its conversation goes back, then activates again.
     agentSignedOut: async (agent) => {
       const version = daemon?.chosenClis().find((cli) => cli.name === agent)?.version ?? "unknown";
@@ -12724,6 +12834,7 @@ async function runDaemon(args) {
     ...timing.activationMs === void 0 ? {} : { deadlineMs: timing.activationMs },
     ...timing.activationPollMs === void 0 ? {} : { pollMs: timing.activationPollMs },
     ...timing.signInRestartMs === void 0 ? {} : { signInRestartMs: timing.signInRestartMs },
+    ...timing.checkInMs === void 0 ? {} : { checkInMs: timing.checkInMs },
     log
   });
   checks = new MachineChecks({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herdingchats/friday",
-  "version": "0.1.567",
+  "version": "0.1.569",
   "description": "Friday, HerdingChats' agent daemon, and the herd command it runs agents with.",
   "license": "MIT",
   "type": "module",
@@ -22,5 +22,5 @@
     "satori": "0.32.0",
     "zod": "4.6.7"
   },
-  "gitHead": "816afa2c448b0a5330ddece39cdb0567ef65a3c5"
+  "gitHead": "ac28f0e97b92fbe2178387595a511d35c3ae4953"
 }