hilos-agent 0.11.1 → 0.11.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Stanley
+
+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

@@ -113,8 +113,11 @@ tools in the machine's config:
 The site does not authorize itself: `readOnlyHint` is informational, while this
 person-owned list decides what may run. Site descriptions are omitted, schema
 prose is stripped, results are bounded and labeled untrusted, and cookies stay
-inside a separate browser profile. The bundled browser bridge currently needs
-Node.js 24 or newer; the rest of the daemon keeps its existing Node.js support.
+inside a separate browser profile. The optional browser bridge needs Node.js 24
+or newer. On Node.js 20 or 22 WebMCP stays unavailable, while the rest of the
+daemon keeps working regardless of whether that optional package was omitted by
+the installer. Run `hilos-agent webmcp doctor` after upgrading Node.js and
+reinstalling the package.
 
 ```sh
 hilos-agent webmcp doctor
@@ -128,7 +131,9 @@ hilos-agent webmcp close
 The daemon adds this capability and its citation rules to agent prompts only
 when the config is valid. Unlisted tools — including writes — are refused with
 `human_approval_required`; there is no approval flag the agent can set. WebMCP
-can never approve or merge hilos work. See the complete contract in
+can never approve or merge hilos work. This wrapper is a policy boundary for
+the bridge, not a sandbox around the coding CLI, which still has the machine
+access its operator granted. See the complete contract in
 [WebMCP in hilos](https://hilos.sh/docs/webmcp).
 
 ## How it works
@@ -309,10 +314,9 @@ safest first:
 
 The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
 you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
-before anything is pushed. OpenCode is the first harness with the runtime-card
-bridge; Claude Code, Codex, Cursor, and other adapters still follow their own
-CLI permission modes until their native approval hooks join the same
-vendor-neutral hilos substrate.
+before anything is pushed. When the workspace grants runtime approvals,
+OpenCode, Cursor, Claude Code, and Codex all pause on the same durable hilos
+permission card. A refusal or broken decision path fails closed.
 
 ## Hooks — keep a raw Codex, Claude Code, or Cursor session in the room
 
@@ -440,18 +444,29 @@ restart — and **deleting** the key counts as off, not as "leave it as it was".
 
 ## Flags
 
-`--join <blob>` · `--channel <id>` · `--config <path>` · `--coding-cmd <cmd>` ·
-`--chat-cmd <cmd>` · `--once` · `--backfill` · `--no-gate` · `--help`
+`--join <blob>` · `--join-stdin` · `--channel <id>` · `--config <path>` ·
+`--url <endpoint>` · `--token <token>` ·
+`--coding-cmd <cmd>` · `--coding-model <tier>` · `--chat-cmd <cmd>` ·
+`--web-search` · `--no-web-search` · `--once` · `--backfill` · `--gate` ·
+`--no-gate` · `--no-reply-bridge` · `--version` · `--help`. Hook installation
+also accepts `--global` or one of `--claude`, `--codex`, and `--cursor`.
+
+`--token` remains only for compatibility with older scripts. Command-line
+arguments can be visible to other processes on the machine, so use
+`--join-stdin`, `HILOS_TOKEN`, or the private config file for credentials.
+Likewise, prefer `--join-stdin` over the legacy `--join <blob>` form for a new
+connection.
 
 Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`, `HILOS_ONCE=1`,
 `HILOS_BACKFILL=1`, `HILOS_UPLOAD_TRANSCRIPTS=1|0`.
 
 ## Releasing
 
-Bump `version` in `package.json`, merge, then tag that commit
-`hilos-agent-v<version>` and push the tag. The `npm-publish` workflow checks
-the tag against the tree, parses every source file on Node 20, 22, and 24,
-and publishes to npm (without provenance while the repository is private:
-npm refuses a provenance bundle from a private source repository, 1182).
-`workflow_dispatch` runs the same pipeline as a dry run. Needs the
-`NPM_TOKEN` repository secret (1094).
+Bump `version` in `package.json`, merge, wait for main CI, then tag that commit
+`hilos-agent-v<version>` and push the tag. The `npm-publish` workflow requires
+that exact version, a commit contained in `main`, and a successful `verify`
+check. It packs and clean-installs the artifact on Node.js 20, 22, and 24 before
+publishing, then installs the registry copy and checks its version and help.
+A manual workflow dispatch is always a dry run and cannot publish. The current
+release path needs the `NPM_TOKEN` repository secret until npm trusted
+publishing is configured (1094, 1211).

package/bin/hilos-agent.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // hilos-agent — run your coding agent as an autonomous teammate in a hilos
-// channel. Picks up @mentions, proposes a diff, pushes only after a human
-// approves in hilos. Your code + credentials never leave your machine.
+// channel. Picks up @mentions and opens a PR by default; --gate adds a human
+// approval checkpoint before the push. Your code + credentials never leave
+// your machine.
 //
 // Usage:
 //   hilos-agent --join <blob>      connect with a copy-paste link from hilos
@@ -35,43 +36,107 @@ function packageVersion() {
   return JSON.parse(readFileSync(pkgPath, "utf8")).version;
 }
 
+function requiredOptionValue(argv, index, option) {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("-")) {
+    throw new Error(`Option ${option} requires a value.`);
+  }
+  return value;
+}
+
+function validateCommand(cmd, positional, { skipShape = false } = {}) {
+  const commands = new Set(["run", "init", "hook", "hooks", "webmcp", "web", "help", "version"]);
+  if (!commands.has(cmd)) {
+    throw new Error(`Unknown command: ${cmd}. Try \`hilos-agent --help\`.`);
+  }
+  if (skipShape) return;
+
+  if (["run", "init", "hook", "help", "version"].includes(cmd) && positional.length > 1) {
+    throw new Error(`Unexpected argument for ${cmd}: ${positional[1]}. Try \`hilos-agent --help\`.`);
+  }
+
+  if (cmd === "hooks") {
+    const subcommand = positional[1];
+    if (!subcommand) throw new Error("A hooks command is required: install or print.");
+    if (!new Set(["install", "print"]).has(subcommand)) {
+      throw new Error(`Unknown hooks command: ${subcommand}. Use install or print.`);
+    }
+    if (positional.length > 2) {
+      throw new Error(`Unexpected argument for hooks ${subcommand}: ${positional[2]}.`);
+    }
+  }
+
+  if (cmd === "web") {
+    const subcommand = positional[1] || "doctor";
+    if (subcommand !== "doctor") {
+      throw new Error(`Unknown web command: ${subcommand}. Try \`hilos-agent web doctor\`.`);
+    }
+    if (positional.length > 2) {
+      throw new Error(`Unexpected argument for web doctor: ${positional[2]}.`);
+    }
+  }
+
+  if (cmd === "webmcp") {
+    const operation = positional[1] || "doctor";
+    const allowed = new Set(["doctor", "login", "open", "tools", "call", "close"]);
+    if (!allowed.has(operation)) {
+      throw new Error(`Unknown webmcp command: ${operation}. Use doctor, login, open, tools, call, or close.`);
+    }
+    const argumentCount = positional.length - 2;
+    const validCount = operation === "login" || operation === "open"
+      ? argumentCount === 1
+      : operation === "call"
+        ? argumentCount === 1 || argumentCount === 2
+        : argumentCount === 0;
+    if (!validCount) {
+      throw new Error(`Invalid arguments for webmcp ${operation}. Try \`hilos-agent --help\`.`);
+    }
+  }
+}
+
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--join") flags.join = argv[++i];
+    if (a === "--join") flags.join = requiredOptionValue(argv, i++, a);
     else if (a === "--join-stdin") flags.joinStdin = true;
-    else if (a === "--config") flags.config = argv[++i];
-    else if (a === "--channel") flags.channelId = argv[++i];
-    else if (a === "--url") flags.url = argv[++i];
-    else if (a === "--token") flags.token = argv[++i];
-    else if (a === "--coding-cmd") flags.codingCmd = argv[++i];
-    else if (a === "--coding-model") flags.codingModel = argv[++i];
-    else if (a === "--chat-cmd") flags.chatCmd = argv[++i];
+    else if (a === "--config") flags.config = requiredOptionValue(argv, i++, a);
+    else if (a === "--channel") flags.channelId = requiredOptionValue(argv, i++, a);
+    else if (a === "--url") flags.url = requiredOptionValue(argv, i++, a);
+    else if (a === "--token") flags.token = requiredOptionValue(argv, i++, a);
+    else if (a === "--coding-cmd") flags.codingCmd = requiredOptionValue(argv, i++, a);
+    else if (a === "--coding-model") flags.codingModel = requiredOptionValue(argv, i++, a);
+    else if (a === "--chat-cmd") flags.chatCmd = requiredOptionValue(argv, i++, a);
     else if (a === "--no-web-search") flags.webSearch = false;
     else if (a === "--web-search") flags.webSearch = true;
     else if (a === "--once") flags.once = true;
     else if (a === "--backfill") flags.backfill = true;
+    else if (a === "--gate") flags.gate = true;
     else if (a === "--no-gate") flags.gate = false;
     else if (a === "--no-reply-bridge") flags.replyBridge = false;
     else if (a === "--global") flags.global = true;
     else if (a === "--claude") flags.hookClient = "claude";
     else if (a === "--codex") flags.hookClient = "codex";
     else if (a === "--cursor") flags.hookClient = "cursor";
-    else if (a === "--vendor") flags.vendor = argv[++i];
+    else if (a === "--vendor") flags.vendor = requiredOptionValue(argv, i++, a);
     else if (a === "--scope-managed") flags.scopeManaged = true;
+    // Marker embedded in self-contained hook commands. It is intentionally
+    // internal: hook.mjs uses it to recognize and replace managed installs.
     else if (a === "--managed-runtime") flags.managedRuntime = true;
     else if (a === "-h" || a === "--help") flags.help = true;
     else if (a === "-v" || a === "--version") flags.version = true;
+    else if (a.startsWith("-")) throw new Error(`Unknown option: ${a}. Try \`hilos-agent --help\`.`);
     else positional.push(a);
   }
-  return { cmd: positional[0] || "run", flags, positional };
+  const cmd = positional[0] || "run";
+  validateCommand(cmd, positional, { skipShape: flags.help || flags.version });
+  return { cmd, flags, positional };
 }
 
 const HELP = `hilos-agent — your coding agent as a teammate in hilos
 
-  hilos-agent --join <blob>      connect using a link copied from hilos
+  hilos-agent --join <blob>      legacy argv-compatible connect link
   hilos-agent --join-stdin       paste the private link at a no-echo prompt
   hilos-agent init               write a starter config to ~/.hilos/agent.json
   hilos-agent webmcp doctor      verify the local WebMCP browser bridge
@@ -82,16 +147,21 @@ const HELP = `hilos-agent — your coding agent as a teammate in hilos
   hilos-agent webmcp close       close the isolated browser session
   hilos-agent web doctor         report this CLI's native public-web capability
   hilos-agent                    run the daemon (watch @mentions, propose diffs)
+  hilos-agent run                same as above, explicit
   hilos-agent hooks install      stream this repo's Codex, Claude, and Cursor
                                  sessions to hilos and continue replies in the same
                                  local session. Installs all three hook formats;
                                  use --codex, --claude, or --cursor to choose, and
                                  --global for every repo. HILOS_HOOKS=off pauses
                                  streaming; HILOS_REPLY_BRIDGE=off pauses pickup.
+  hilos-agent hooks print        preview the hook configuration without writing
 
 Options:
   --channel <id>     watch only one channel (per-channel override)
   --config <path>    use a specific config file
+  --url <endpoint>   override the MCP endpoint (or use HILOS_URL/config)
+  --token <token>    legacy token override; argv may be visible to other local
+                     processes. Prefer --join-stdin or HILOS_TOKEN.
   --coding-cmd <cmd> the coding agent to run — claude -p, codex exec,
                      cursor-agent -p --trust, opencode run, agy -p, hermes -z,
                      or any command
@@ -104,10 +174,12 @@ Options:
   --chat-cmd <cmd>   fast command for chat replies + the plan-ack (default:
                      derived from the coding command, so a Codex or Cursor
                      daemon chats with its own tool)
+  --web-search       allow hilos to request native public web tools (default)
   --no-web-search    stop hilos from enabling/requesting native public web
   --once             one poll then exit (cron-friendly)
   --backfill         also act on mentions that predate startup
-  --no-gate          propose only; don't wait for approval / push
+  --gate             wait for approval in hilos before pushing a branch
+  --no-gate          open a PR directly without pre-push approval (default)
   --no-reply-bridge  don't resume local sessions from replies in bound threads
   -v, --version      print the installed version
   -h, --help         this help
@@ -158,6 +230,7 @@ async function main() {
     const starter = { ...(joinPayload || {}) };
     if (flags.codingCmd) starter.codingCmd = flags.codingCmd;
     if (flags.codingModel) starter.codingModel = flags.codingModel;
+    if (flags.gate !== undefined) starter.gate = flags.gate;
     const path = writeStarterConfig(joinPayload ? GLOBAL_CONFIG : flags.config, starter);
     console.log(`Wrote ${path}.`);
     console.log(joinPayload ? "Token + endpoint set from your link." : "Fill in token + repos, then run `hilos-agent`.");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.1",
-  "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
+  "version": "0.11.2",
+  "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. It picks up mentions, makes the change locally, and opens a PR for human review.",
   "type": "module",
   "bin": {
     "hilos-agent": "bin/hilos-agent.mjs"
@@ -30,10 +30,12 @@
     "claude-code",
     "codex",
     "cursor",
+    "opencode",
+    "hermes-agent",
     "coding-agent"
   ],
   "license": "MIT",
-  "dependencies": {
-    "agent-browser": "^0.35.0"
+  "optionalDependencies": {
+    "agent-browser": "^0.36.0"
   }
 }

package/src/acp-session.mjs

@@ -191,6 +191,7 @@ export function createNdjsonParser() {
  *   requestPermission?: (request: object, context: object) => Promise<unknown>,
  *   getPermissionDecision?: (handle: unknown, context: object) => Promise<unknown>,
  *   mcpServers?: object[],
+ *   beforeSpawn?: () => boolean | Promise<boolean>,
  *   spawnImpl?: (cmd: string, args: string[], options: object) => import("node:child_process").ChildProcess,
  *   setTimer?: typeof setTimeout,
  *   clearTimer?: typeof clearTimeout,
@@ -217,6 +218,7 @@ export async function runAcpSession({
   /** Session to continue (0778); null starts a fresh one. */
   resumeSessionId = null,
   mcpServers = [],
+  beforeSpawn,
   spawnImpl = spawn,
   setTimer = setTimeout,
   clearTimer = clearTimeout,
@@ -264,6 +266,7 @@ export async function runAcpSession({
   let currentMessageId = null;
   let messageBuffer = "";
   const eventMapper = createAcpEventMapper();
+  let authorityLost = false;
 
   const emitOutput = (text) => {
     try {
@@ -411,6 +414,17 @@ export async function runAcpSession({
   }
 
   try {
+    if (typeof beforeSpawn === "function") {
+      try {
+        if ((await beforeSpawn()) === false) {
+          authorityLost = true;
+          throw new Error("execution authority lost before ACP spawn");
+        }
+      } catch (error) {
+        authorityLost = true;
+        throw error;
+      }
+    }
     child = spawnImpl(cmd, acpArgs, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
     const spawned = new Promise((resolve, reject) => {
       child.once("spawn", resolve);
@@ -508,13 +522,14 @@ export async function runAcpSession({
     };
   } catch (error) {
     flushMessage();
-    const aborted = abortKind === "cancelled";
+    const aborted = abortKind === "cancelled" || authorityLost;
     const timedOut = abortKind === "timeout";
     return {
       status: null,
       stdout: stdout.trimEnd(),
       stderr: stderr.trimEnd(),
       ...(aborted ? { aborted: true } : {}),
+      ...(authorityLost ? { authorityLost: true } : {}),
       ...(sessionId ? { sessionId } : {}),
       error:
         error instanceof Error && !timedOut

package/src/cli.mjs

@@ -179,6 +179,9 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  *   BEFORE the ungated compat retry is spawned when a CLI rejects the 0777
  *   permission flags (0785), so the caller can warn its room while the run can
  *   still be stopped. A throw here never fails the run.
+ * @property {() => (boolean | Promise<boolean>)} [beforeSpawn] - fail-closed
+ *   authority check, awaited immediately before each child-process attempt.
+ *   Returning false or throwing prevents that spawn and marks the run aborted.
  */
 
 /**
@@ -191,7 +194,7 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  *
  * @param {RunCliOptions} opts
  */
-function runCliOnce(opts) {
+async function runCliOnce(opts) {
   const {
     cmd,
     args = [],
@@ -204,7 +207,37 @@ function runCliOnce(opts) {
     signal,
     onData,
     env,
+    beforeSpawn,
   } = opts || {};
+  // This guard belongs at the process boundary, after all potentially-slow
+  // caller setup and once per compatibility retry. Checking in runCli's caller
+  // leaves a race before the first child and lets its internal retries escape.
+  if (signal?.aborted) {
+    return { status: null, stdout: "", stderr: "", aborted: true, error: new Error("cancelled") };
+  }
+  if (typeof beforeSpawn === "function") {
+    try {
+      if ((await beforeSpawn()) === false) {
+        return {
+          status: null,
+          stdout: "",
+          stderr: "",
+          aborted: true,
+          authorityLost: true,
+          error: new Error("execution authority lost before spawn"),
+        };
+      }
+    } catch (error) {
+      return {
+        status: null,
+        stdout: "",
+        stderr: "",
+        aborted: true,
+        authorityLost: true,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
   return new Promise((resolve) => {
     // Already cancelled before we even start.
     if (signal?.aborted) {

package/src/codex-mcp-session.mjs

@@ -160,6 +160,7 @@ export function mapCodexDecision(reply, availableDecisions) {
  *   onEvent?: (event: object) => void,
  *   requestPermission?: (request: object, context: object) => Promise<unknown>,
  *   getPermissionDecision?: (handle: unknown, context: object) => Promise<unknown>,
+ *   beforeSpawn?: () => boolean | Promise<boolean>,
  *   spawnImpl?: typeof spawn,
  *   sleep?: (ms: number) => Promise<void>,
  *   now?: () => number,
@@ -185,6 +186,7 @@ export async function runCodexMcpSession({
   onEvent,
   requestPermission,
   getPermissionDecision,
+  beforeSpawn,
   spawnImpl = spawn,
   sleep,
   now = () => Date.now(),
@@ -199,6 +201,40 @@ export async function runCodexMcpSession({
   if (signal?.aborted) onOuterAbort();
   else signal?.addEventListener("abort", onOuterAbort, { once: true });
 
+  if (typeof beforeSpawn === "function") {
+    try {
+      if ((await beforeSpawn()) === false) {
+        signal?.removeEventListener("abort", onOuterAbort);
+        return {
+          status: null,
+          stdout: "",
+          stderr: "",
+          error: new Error("execution authority lost before Codex MCP spawn"),
+          sessionId: null,
+          initialized: false,
+          sawFrame: false,
+          exitCode: null,
+          aborted: true,
+          authorityLost: true,
+        };
+      }
+    } catch (error) {
+      signal?.removeEventListener("abort", onOuterAbort);
+      return {
+        status: null,
+        stdout: "",
+        stderr: "",
+        error: error instanceof Error ? error : new Error(String(error)),
+        sessionId: null,
+        initialized: false,
+        sawFrame: false,
+        exitCode: null,
+        aborted: true,
+        authorityLost: true,
+      };
+    }
+  }
+
   const child = spawnImpl(cmd, serverArgs, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
   const parser = createNdjsonParser();
   const pending = new Map();

package/src/config.mjs

@@ -2,9 +2,18 @@
 // overlaid by env vars and CLI flags / a --join blob. The join blob carries the
 // MCP url + token (+ optional channel) so a user can paste one command.
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 
 export const GLOBAL_CONFIG = join(homedir(), ".hilos", "agent.json");
 export const LOCAL_CONFIG = "hilos-agent.json";
@@ -347,7 +356,16 @@ export function reloadConfig(prev) {
 /** Write a starter config file (used by `hilos-agent init`). */
 export function writeStarterConfig(path, partial = {}) {
   const target = path || GLOBAL_CONFIG;
-  mkdirSync(dirname(target), { recursive: true });
+  const targetDir = dirname(target);
+  const directoryExisted = existsSync(targetDir);
+  mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+  // A newly created credentials directory must be private. Also repair the
+  // default ~/.hilos directory if an older install created it permissively,
+  // without unexpectedly chmod'ing an arbitrary existing directory supplied
+  // through --config (which may be a repository root).
+  if (!directoryExisted || resolve(targetDir) === resolve(dirname(GLOBAL_CONFIG))) {
+    chmodSync(targetDir, 0o700);
+  }
   const starter = {
     url: partial.url || DEFAULTS.url,
     token: partial.token || "",
@@ -358,8 +376,24 @@ export function writeStarterConfig(path, partial = {}) {
     webSearch: partial.webSearch !== false,
     defaultBranch: DEFAULTS.defaultBranch,
     // false = open a PR directly (bias to action); true = approve-before-push.
-    gate: false,
+    gate: partial.gate === true,
   };
-  writeFileSync(target, JSON.stringify(starter, null, 2) + "\n");
+  // Write beside the destination and rename it into place so a crash cannot
+  // leave a truncated token file. The temporary starts private, and replacing
+  // an older 0644 file also tightens the final path to 0600 in one rename.
+  const temporary = join(
+    targetDir,
+    `.${basename(target)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  try {
+    writeFileSync(temporary, JSON.stringify(starter, null, 2) + "\n", {
+      flag: "wx",
+      mode: 0o600,
+    });
+    renameSync(temporary, target);
+    chmodSync(target, 0o600);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
   return target;
 }

package/src/cursor-store.mjs

@@ -7,10 +7,9 @@
 // restart resumes from it — bounded by `catchupMs`, because replaying a week of
 // stale asks after a vacation would be worse than skipping them.
 //
-// Telegram semantics, deliberately: persisting the cursor acknowledges
-// DELIVERY into the daemon's queue, not completion of the work. A crash after
-// enqueue can still lose an in-flight task (exactly as today); what can no
-// longer happen is a mention arriving into a dead daemon and never being seen.
+// Persisting the cursor acknowledges a safely completed queue lifecycle, not
+// delivery into volatile memory. New servers add the mention-table ingestion
+// sequence, so edits/rebuilds and equal-timestamp siblings cannot be skipped.
 //
 // Dependency-free and injectable-dir like hook.mjs's state store, so tests run
 // against a temp dir and never touch a real ~/.hilos.
@@ -38,6 +37,13 @@ export function cursorPath(agentId, dir = CURSOR_STATE_DIR) {
  * @returns {string|null} ISO timestamp
  */
 export function loadMentionCursor(agentId, { catchupMs = 0, dir = CURSOR_STATE_DIR, now = Date.now } = {}) {
+  return loadMentionCursorState(agentId, { catchupMs, dir, now })?.createdAt ?? null;
+}
+
+export function loadMentionCursorState(
+  agentId,
+  { catchupMs = 0, dir = CURSOR_STATE_DIR, now = Date.now } = {},
+) {
   if (!agentId || !(catchupMs > 0)) return null;
   let parsed;
   try {
@@ -50,7 +56,24 @@ export function loadMentionCursor(agentId, { catchupMs = 0, dir = CURSOR_STATE_D
   const at = new Date(value).getTime();
   if (Number.isNaN(at)) return null;
   const floor = now() - catchupMs;
-  return at < floor ? new Date(floor).toISOString() : value;
+  const mentionSeq = Number.isSafeInteger(parsed.mentionCursorSeq) && parsed.mentionCursorSeq >= 0
+    ? parsed.mentionCursorSeq
+    : null;
+  if (mentionSeq != null) {
+    // Sequence progress belongs to the ingestion checkpoint, not to the
+    // original message timestamp: editing a year-old message creates fresh
+    // sequence work. New state records when the checkpoint was written so the
+    // catch-up window still bounds genuinely abandoned daemons. Pre-release
+    // sequence files without this additive field remain usable.
+    if (typeof parsed.mentionCursorSavedAt === "string") {
+      const savedAt = new Date(parsed.mentionCursorSavedAt).getTime();
+      if (!Number.isFinite(savedAt)) return null;
+      if (savedAt < floor) return { createdAt: new Date(floor).toISOString(), mentionSeq: null };
+    }
+    return { createdAt: value, mentionSeq };
+  }
+  if (at < floor) return { createdAt: new Date(floor).toISOString(), mentionSeq: null };
+  return { createdAt: value, mentionSeq: null };
 }
 
 /**
@@ -60,14 +83,26 @@ export function loadMentionCursor(agentId, { catchupMs = 0, dir = CURSOR_STATE_D
  *
  * @param {string} agentId
  * @param {string} isoTimestamp
- * @param {{ dir?: string, log?: { error?: (m: string) => void } }} [opts]
+ * @param {{ dir?: string, log?: { error?: (m: string) => void }, mentionSeq?: number|null, now?: () => number }} [opts]
  * @returns {boolean} whether the write landed
  */
-export function saveMentionCursor(agentId, isoTimestamp, { dir = CURSOR_STATE_DIR, log } = {}) {
+export function saveMentionCursor(
+  agentId,
+  isoTimestamp,
+  { dir = CURSOR_STATE_DIR, log, mentionSeq = null, now = Date.now } = {},
+) {
   if (!agentId || typeof isoTimestamp !== "string" || !isoTimestamp) return false;
   try {
     mkdirSync(dir, { recursive: true });
-    writeFileSync(cursorPath(agentId, dir), JSON.stringify({ mentionCursor: isoTimestamp }));
+    writeFileSync(
+      cursorPath(agentId, dir),
+      JSON.stringify({
+        mentionCursor: isoTimestamp,
+        ...(Number.isSafeInteger(mentionSeq) && mentionSeq >= 0
+          ? { mentionCursorSeq: mentionSeq, mentionCursorSavedAt: new Date(now()).toISOString() }
+          : {}),
+      }),
+    );
     return true;
   } catch (e) {
     log?.error?.(`mention cursor not persisted: ${e?.message || e}`);