hilos-agent 0.11.13 → 0.11.15

package/src/iterate-claim-recovery.mjs

@@ -138,10 +138,23 @@ export function defaultProcessInstanceIdentity(
   }
 }
 
+// A directory fsync only hardens the rename/link against power loss; it never
+// decides who owns the seat. Windows refuses FlushFileBuffers on a directory
+// handle (EPERM), and some filesystems answer EINVAL or EBADF. Before 1330 that
+// throw was caught by acquireLock's publish step and reported as "another
+// local daemon already owns this agent", so every Windows daemon refused to
+// start against an empty lock directory.
 function syncDirectory(fs, path) {
-  const fd = fs.openSync(path, "r");
+  let fd;
+  try {
+    fd = fs.openSync(path, "r");
+  } catch {
+    return;
+  }
   try {
     fs.fsyncSync(fd);
+  } catch {
+    /* durability nicety only; the link/unlink already happened */
   } finally {
     fs.closeSync(fd);
   }
@@ -178,6 +191,10 @@ export function createIterateClaimRecoveryStore({
   const processInstanceIdentity = getProcessInstanceIdentity(pid);
   let lockHeld = false;
   let heldElectionPath = null;
+  // Why the last acquireLock() returned false: "contended" when a live daemon
+  // holds the seat, otherwise the filesystem error. run.mjs turns this into
+  // an honest startup message (1330).
+  let lastAcquireFailure = null;
 
   function ensureScope() {
     fs.mkdirSync(scopeDir, { recursive: true, mode: 0o700 });
@@ -360,9 +377,11 @@ export function createIterateClaimRecoveryStore({
     acquireLock() {
       if (lockHeld) return true;
       if (!ownerKey || !processInstanceIdentity) return false;
+      lastAcquireFailure = null;
       try {
         ensureScope();
       } catch (error) {
+        lastAcquireFailure = `lock directory unavailable (${scopeDir}): ${error?.message || error}`;
         log?.error?.(`iterate claim scope unavailable: ${error?.message || error}`);
         return false;
       }
@@ -392,12 +411,14 @@ export function createIterateClaimRecoveryStore({
           }
         }
         removeOwnCandidate();
+        lastAcquireFailure = `lock file not written (${scopeDir}): ${error?.message || error}`;
         log?.error?.(`iterate claim scope not locked: ${error?.message || error}`);
         return false;
       }
 
       if (!acquireElection()) {
         removeOwnCandidate();
+        lastAcquireFailure = "contended";
         return false;
       }
 
@@ -408,6 +429,7 @@ export function createIterateClaimRecoveryStore({
           .filter((name) => name.startsWith(".owner.") && name.endsWith(".lock"));
       } catch (error) {
         removeOwnPublishedLock();
+        lastAcquireFailure = `lock directory not readable (${scopeDir}): ${error?.message || error}`;
         log?.error?.(`iterate claim scope not inspected: ${error?.message || error}`);
         return false;
       }
@@ -440,6 +462,7 @@ export function createIterateClaimRecoveryStore({
 
       if (!ownSeen || liveContender) {
         removeOwnPublishedLock();
+        lastAcquireFailure = "contended";
         return false;
       }
 
@@ -460,6 +483,11 @@ export function createIterateClaimRecoveryStore({
       return true;
     },
 
+    /** Why the last acquireLock() failed: "contended" or a filesystem reason. */
+    acquireFailure() {
+      return lastAcquireFailure;
+    },
+
     releaseLock() {
       if (!ownsPublishedLock()) return false;
       if (!removeOwnPublishedLock()) {

package/src/run.mjs

@@ -15,6 +15,7 @@ import { startWake, createWakeGate } from "./wake.mjs";
 import { scanReplyBridge, handleReplyBridgeJob } from "./reply-bridge.mjs";
 import { detectVendor, fastChatCmd, webCapability } from "./progress-emitter.mjs";
 import { commandArgv } from "./argv.mjs";
+import { resolveCommand } from "./cli.mjs";
 import {
   createIterateClaimRecoveryStore,
   reconcileDaemonIterateClaims,
@@ -22,6 +23,24 @@ import {
 
 const MAX_IMMEDIATE_SEQUENCE_PAGES = 8;
 
+// 1290: the hilos.sh contract. Missing-tool paths exist only for injected tests;
+// tools/list remains the token's prompt inventory and the recall scope check.
+const HILOS_DAEMON_TOOLS = Object.freeze({
+  editMessage: true, postProgress: true, runs: true, review: true,
+  recall: true, agentIntent: true, prActions: true, runtimePermissions: true,
+  uploadTranscript: true, hepEvents: true, runInputs: true, react: true,
+  decisionWaitMs: 20_000,
+});
+
+/** Where to get the vendor CLI a daemon command names (1330). */
+function installHint(vendor) {
+  if (vendor === "cursor") return "the Cursor CLI is separate from the Cursor app (macOS/Linux: curl https://cursor.com/install -fsS | bash; Windows: irm https://cursor.com/install -useb | iex)";
+  if (vendor === "claude_code") return "npm install -g @anthropic-ai/claude-code";
+  if (vendor === "codex") return "npm install -g @openai/codex";
+  if (vendor === "opencode") return "https://opencode.ai";
+  return "";
+}
+
 /**
  * The poll loop. Embeddable: pass a `signal` to stop it cleanly (interrupts the
  * inter-poll sleep, cancels the active job, then resolves) and an `onEvent`
@@ -30,6 +49,7 @@ const MAX_IMMEDIATE_SEQUENCE_PAGES = 8;
  *
  * @param {any} cfg
  * @param {{
+ *   testServerFixture?: any,
  *   handler?: (ctx: any, cfg: any, deps?: any, opts?: any) => Promise<any>,
  *   log?: any,
  *   signal?: AbortSignal,
@@ -45,6 +65,7 @@ export async function run(
   cfg,
   {
     handler = handleTask,
+    testServerFixture,
     log = console,
     signal,
     onEvent,
@@ -143,8 +164,7 @@ export async function run(
     // Throw for the same reason as the token guard above — embed-safe, CLI-equal.
     throw new Error("This agent has no display name / handle — set one in hilos, then reconnect.");
   }
-  // Initialized only after the server advertises the complete recovery
-  // protocol below. Older servers keep their pre-recovery Iterate behavior.
+  // Initialized after discovery so the recovery lock is scoped to this agent.
   let iterateClaimRecoveryStore = null;
   let queue = null;
   let wake = null;
@@ -178,6 +198,19 @@ export async function run(
     enabled: cfg.webSearch !== false,
     args: commandArgv(cfg.codingCmd).slice(1),
   });
+  // 1330 — say at startup, not at the first mention, when the CLI this daemon
+  // is configured to drive is not installed. A person who connected through an
+  // IDE agent read "Hilo is connected and online" and then got "(my chat
+  // command `cursor-agent …` isn't installed or on PATH.)" in the room.
+  for (const [role, command] of [["chat", chatCommand], ["code", cfg.codingCmd]]) {
+    const bin = commandArgv(command)[0];
+    if (!bin || resolveCommand(bin)) continue;
+    const hint = installHint(detectVendor(command));
+    log.error(
+      `${role} command not found: \`${bin}\` is not installed or not on PATH${hint ? ` — ${hint}` : ""}. Mentions will fail until it is.`,
+    );
+    emit({ type: "status", text: `${role} command missing: ${bin}` });
+  }
   log.log(
     chatVendor === codingVendor && web.status === codingWeb.status
       ? `web: ${web.status} — ${web.source}`
@@ -186,29 +219,20 @@ export async function run(
 
   const since = cfg.backfill ? 0 : Date.now();
   // listTools (schemas included) is the primary read; a client exposing only
-  // listToolNames (an embedder's minimal mock, or an older embedded client)
-  // still names the tools — it just never advertises arg-level capabilities.
+  // listToolNames is a minimal embedded test client. Schemas no longer
+  // control production behavior.
   const toolList = typeof listTools === "function" ? await listTools({ signal: runSignal }) : [];
   const toolNames = toolList.length
     ? toolList.map((t) => t.name)
     : typeof listToolNames === "function"
       ? await listToolNames({ signal: runSignal })
       : [];
-  // Arg-level capability sniffing (0866): a long-poll-capable server declares
-  // `waitMs` in the tool's inputSchema. Absent (older server) → the daemon
-  // falls back to plain interval polling, exactly as before.
-  const toolArgProps = (name) =>
-    toolList.find((t) => t.name === name)?.inputSchema?.properties ?? {};
-  const serverMentionWait = "waitMs" in toolArgProps("list_mentions");
-  const serverMentionSequence = "sinceMentionSeq" in toolArgProps("list_mentions");
-  const serverMentionSequenceBootstrap = "initializeMentionSeq" in toolArgProps("list_mentions");
-  const serverDecisionWait = "waitMs" in toolArgProps("get_permission_decision");
-  const updateRunArgs = toolArgProps("update_run");
-  const serverIterateClaimRecovery =
-    "claimId" in updateRunArgs &&
-    "confirmIterateClaim" in updateRunArgs &&
-    "releaseIterateClaim" in updateRunArgs;
-  if (me.agentId && serverIterateClaimRecovery) {
+  // Schema omissions are fixtures, never version negotiation with hilos.sh.
+  const mentionWaitEnabled = testServerFixture?.mentionWait ?? true;
+  const mentionSequenceEnabled = testServerFixture?.mentionSequence ?? true;
+  const mentionSequenceBootstrapEnabled = testServerFixture?.mentionSequenceBootstrap ?? true;
+  const iterateClaimRecoveryEnabled = testServerFixture?.iterateClaimRecovery ?? true;
+  if (me.agentId && iterateClaimRecoveryEnabled) {
     iterateClaimRecoveryStore = createIterateClaimRecoveryStore({
       agentId: me.agentId,
       url: cfg.url,
@@ -217,7 +241,12 @@ export async function run(
       log,
     });
     if (!iterateClaimRecoveryStore.acquireLock()) {
-      throw new Error("Another local daemon already owns this agent and server connection.");
+      const why = iterateClaimRecoveryStore.acquireFailure?.();
+      throw new Error(
+        why && why !== "contended"
+          ? `The local run lock could not be taken: ${why}. Make that directory writable and start again.`
+          : "Another local daemon already owns this agent and server connection.",
+      );
     }
     reconcileClaimsOnce = async (context) => {
       try {
@@ -239,64 +268,13 @@ export async function run(
       }
     };
   }
-  // Capabilities of THIS server, so the handler degrades gracefully on older
-  // deploys (e.g. no edit_message → no live heartbeat, rather than erroring).
-  const caps = {
-    editMessage: toolNames.includes("edit_message"),
-    postProgress: toolNames.includes("post_progress"),
-    // The RUNS entity (0279/0280): when absent (older server) the handler skips
-    // start_run/update_run silently and behaves exactly as before.
-    runs: toolNames.includes("start_run"),
-    // Cross-agent REVIEW execution (0288): the reviewer needs to read a PR's diff
-    // AND post an advisory review. Absent on older servers → review-requests fall
-    // through to today's chat/code behavior, exactly as before.
-    review: toolNames.includes("post_review") && toolNames.includes("get_pr_diff"),
-    // Agent memory (0297): when present the handler best-effort recalls team
-    // learnings before each coding task and prepends them to the prompt so the
-    // coding agent has the workspace's conventions and gotchas from the start.
-    // Absent on older servers → silently skipped, no change in behavior.
-    recall: toolNames.includes("recall"),
-    // Semantic local-folder intent (0515): the server guarantees a forced-tool
-    // ask/ship/deploy decision. Older servers fall back to the local router.
-    agentIntent: toolNames.includes("classify_agent_intent"),
-    // Relaying a human's merge/close instruction (0701/0704). Both tools are
-    // required; on an older server the daemon simply never relays and behaves
-    // exactly as before. The authority is the server's either way — the daemon
-    // only passes along the id of the message that asked.
-    prActions: toolNames.includes("merge_pr") && toolNames.includes("close_pr"),
-    // Harness-enforced runtime permission bridge (0593). Both tools are
-    // required: a request without a durable reply path must fail closed.
-    runtimePermissions:
-      toolNames.includes("request_permission") &&
-      toolNames.includes("get_permission_decision"),
-    // Opt-in run transcripts (0792). Two gates, and BOTH must say yes: the
-    // server has to offer the tool, and the operator has to have turned
-    // `uploadTranscripts` on. Older servers simply never see the call.
-    uploadTranscript: toolNames.includes("upload_run_transcript"),
-    // Runtime-neutral replay exhaust (1148). The daemon only projects local
-    // coding streams when this exact ingest boundary exists; older servers
-    // keep the current progress/transcript behavior byte-for-byte.
-    hepEvents: toolNames.includes("append_run_events"),
-    // Room directions for a running job (1181/1182). When the server can take
-    // the receipt, the daemon declares `next_turn` at start_run, reads
-    // `pendingInputs` off its heartbeat, and runs one more turn with them.
-    // Older servers never list a direction, and the daemon never declares.
-    runInputs: toolNames.includes("acknowledge_run_input"),
-    // Emoji reactions (0860): the lightest answer to an untagged DM message
-    // that needs no words. Absent on older servers → the agent stays quiet
-    // instead, exactly as if it had no hand to wave.
-    react: toolNames.includes("add_reaction"),
-    // Long-poll hold for the permission gate (0866): each decision read blocks
-    // server-side until a human decides, so an Allow reaches the paused tool in
-    // under a second instead of on the gate's next poll. 0 on older servers.
-    decisionWaitMs: serverDecisionWait ? 20000 : 0,
-  };
+  const testCapabilities = testServerFixture?.capabilities ?? HILOS_DAEMON_TOOLS;
+  // 0513 is an authorization boundary, not an older-server fallback: a
+  // channel-bound token is never advertised workspace memory.
+  const canRecall = toolNames.includes("recall");
 
-  // The wake doorbell (0824): capability-checked like every optional surface.
-  // On an older server the tool is absent and the daemon polls exactly as
-  // before; with it, a new message in the workspace rings a content-free
-  // Realtime broadcast that cuts mention pickup from pollMs to instant.
-  if (toolNames.includes("get_wake_channel")) {
+  // The doorbell is always registered. Polling still survives a network failure.
+  if (testServerFixture?.wake !== false) {
     try {
       const chan = await tool("get_wake_channel");
       if (chan?.url && chan?.topic) {
@@ -327,12 +305,11 @@ export async function run(
 
   // Register local folders (0324/0325): a folder-mode daemon announces each
   // channel→folder mapping to the server so the channel shows a folder chip
-  // without any manual step. Capability-gated on the server advertising
-  // link_folder (older deploys skip silently, exactly like recall). Best-effort:
+  // without any manual step. Best-effort:
   // each call is wrapped so a failure logs one line and NEVER blocks startup.
   // Done ONCE here at startup — config live-reload (reloadConfig, below) does NOT
   // re-register, so a folders entry added while running needs a restart to link.
-  if (toolNames.includes("link_folder") && cfg.folders && Object.keys(cfg.folders).length) {
+  if (testServerFixture?.linkFolder !== false && cfg.folders && Object.keys(cfg.folders).length) {
     for (const [channelId, path] of Object.entries(cfg.folders)) {
       if (!channelId || !path) continue;
       const title = basename(path);
@@ -377,9 +354,9 @@ export async function run(
   if (persistedCursor) log.log(`resuming mention cursor from ${persistedCursor}`);
   const cursor = {
     value: persistedCursor ?? (since ? new Date(since).toISOString() : null),
-    seq: serverMentionSequence ? persistedCursorState?.mentionSeq ?? null : null,
+    seq: mentionSequenceEnabled ? persistedCursorState?.mentionSeq ?? null : null,
   };
-  let mentionSequenceActive = serverMentionSequence && cursor.seq != null;
+  let mentionSequenceActive = mentionSequenceEnabled && cursor.seq != null;
   // Fetch progress is deliberately volatile. It moves through pages as soon as
   // the server scans them (so an active job does not hot-poll one seen row),
   // while `cursor` moves only after queue/recovery settlement. A restart always
@@ -404,7 +381,7 @@ export async function run(
     // Deploy, dispatch, ambient, and DM projections are useful intake, but are
     // not rows in the explicit mention scan. They must never advance that
     // durable high-watermark.
-    if (serverMentionSequence && mentionSeq == null) return;
+    if (mentionSequenceEnabled && mentionSeq == null) return;
     const key = batchKey(timestamp, mentionSeq);
     let batch = cursorBatches.get(key);
     if (!batch) {
@@ -573,7 +550,8 @@ export async function run(
           channelId,
           tool: taskTool,
           me,
-          caps,
+          testCapabilities,
+          canRecall,
           iterateClaimRecoveryStore,
         },
         liveCfg,
@@ -700,7 +678,7 @@ export async function run(
   // moment a mention lands — pickup latency stops being pollMs. The server
   // caps a hold at 25s; asking for more just gets 25s.
   const mentionWaitMs = () =>
-    serverMentionWait && liveCfg.longPollMs > 0 ? Math.floor(liveCfg.longPollMs) : 0;
+    mentionWaitEnabled && liveCfg.longPollMs > 0 ? Math.floor(liveCfg.longPollMs) : 0;
 
   async function passViaMentions(immediatePage = 1) {
     const waitMs = mentionWaitMs();
@@ -709,7 +687,7 @@ export async function run(
       ...(mentionSequenceActive && fetchCursor.seq != null
         ? { sinceMentionSeq: fetchCursor.seq }
         : {}),
-      ...(serverMentionSequenceBootstrap && !mentionSequenceActive
+      ...(mentionSequenceBootstrapEnabled && !mentionSequenceActive
         ? { initializeMentionSeq: true }
         : {}),
       ...(cfg.channelId ? { channelId: cfg.channelId } : {}),
@@ -720,7 +698,7 @@ export async function run(
     // 1247 — the server may send a rendered roster per channel alongside the
     // mentions. Stamp it on the row so the CLI prompt can carry it, and cache
     // it for the reply bridge, which polls bound threads instead of mentions.
-    // Absent on an older server; then nothing changes.
+    // Roster enrichment is optional; task delivery does not depend on it.
     const rosters = out?.rosters && typeof out.rosters === "object" ? out.rosters : null;
     if (rosters) {
       for (const m of mentions) {
@@ -768,7 +746,7 @@ export async function run(
         settledEmptySequencePage = true;
       }
     } else if (
-      serverMentionSequenceBootstrap &&
+      mentionSequenceBootstrapEnabled &&
       !mentionSequenceActive &&
       Number.isSafeInteger(announcedSequence) &&
       announcedSequence >= 0 &&