hilos-agent 0.10.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
@@ -158,7 +163,16 @@ can never approve or merge hilos work. See the complete contract in
   PR thread is executed, not described. The daemon relays the request to hilos
   with the id of the message that asked; hilos verifies the person's role and
   that their message really asks for it, then acts with the workspace's GitHub
-  App. The daemon never merges on its own judgment and holds no merge rights.
+  App. If GitHub reports a same-repository merge conflict, the daemon keeps the
+  same turn alive: it fetches the base branch, starts a real two-parent merge on
+  the existing PR branch, names the conflicted files to the coding agent,
+  verifies that no unmerged entries or conflict markers remain, and pushes the
+  repaired head for fresh human review. It never opens a replacement PR or
+  silently merges after repair. Fork PRs stop with an explicit writable-branch
+  boundary. The daemon never merges on its own judgment and holds no merge
+  rights. With `gate:true`, this existing-branch repair still pushes so the PR
+  can return for fresh review. It is the only approve-before-push exception;
+  the repaired head remains unmerged and needs a new approval.
 - **Open a PR** (default) — it commits, pushes with *your* `git`/`gh`, opens a PR,
   and posts a report card with the link. Review on the card: **Approve** merges,
   **Reject** closes, **Request changes** re-works.
@@ -300,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
 
@@ -396,6 +409,16 @@ hilos's GitHub App only for workspace owners/admins). Want a human checkpoint
 before anything is pushed? Set `"gate": true`. Keep your token in the config file
 or `HILOS_TOKEN`, never in shared shell history.
 
+### Durable activity, not raw output
+
+On a current hilos server, daemon-launched Claude Code, Codex, Cursor, and
+OpenCode repo runs automatically keep the same bounded activity facts used by
+the live card—phases, tool/file activity, notes, reported usage, and completion—
+in hilos's runtime-neutral event record. Writes are batched, retry-safe,
+bounded to two one-second attempts, re-authorized and redacted on the server,
+and never allowed to fail the coding run. Raw stdout is not sent by this path.
+An older server simply leaves it off.
+
 ### Run transcripts are opt-in
 
 The room gets what a teammate needs to see: a plan, live progress, a report, a
@@ -421,8 +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, 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.10.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"
@@ -12,7 +12,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "homepage": "https://hilos.sh",
   "repository": {
@@ -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;
 }