@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/daemon/lifetime/daemon-usefulness.js

@@ -19,7 +19,7 @@
  * anybody could lose. When it does shut down, the MCP proxy reconnects and `ensureDaemon` spawns a
  * fresh one on the next call, which is a path already exercised hundreds of times a day.
  */
-import { STATUS_HOLD_MS } from '@reticlehq/core';
+import { SESSION_LIFECYCLE, STATUS_HOLD_MS } from '@reticlehq/core';
 /** Set the first time any tool is dispatched through runTool — the chokepoint every path shares. */
 let servedToolCall = false;
 export function noteToolCall() {
@@ -48,10 +48,20 @@ export function noteSetupHold(now) {
 function setupHolding(now) {
     return undefined !== setupHeldAt && now - setupHeldAt < SETUP_HOLD_MS;
 }
+/** When an agent last attached or detached. Undefined until the first one. */
+let agentSeenAt;
+/** Call on each attach and each detach of an agent. */
+export function noteAgentPresence(now) {
+    agentSeenAt = now;
+}
+function agentRecent(now) {
+    return undefined !== agentSeenAt && now - agentSeenAt < SESSION_LIFECYCLE.DAEMON_AGENT_RECENT_MS;
+}
 /** Tests only. */
 export function resetDaemonUsefulness() {
     servedToolCall = false;
     setupHeldAt = undefined;
+    agentSeenAt = undefined;
 }
 /**
  * True when the daemon has done nothing for anyone and has nothing to lose by exiting.
@@ -72,8 +82,9 @@ export function isUselessDaemon(facts) {
  * no app and sit there for the length of an editor session.
  */
 export function buildIdlePredicate(agentConnected, sessions, pool, now = () => Date.now()) {
+    // An agent that attached recently counts as attached: see DAEMON_AGENT_RECENT_MS.
     return () => !setupHolding(now()) &&
-        (!agentConnected() ||
+        (!(agentConnected() || agentRecent(now())) ||
             isUselessDaemon({
                 servedToolCall: everServedToolCall(),
                 everConnected: sessions.everConnected(),

package/dist/command/daemon/wake-decision.js

@@ -30,9 +30,11 @@ export const WakeAction = {
  * prevent.
  */
 export function decideWake(presence, daemonProjectId, callerProjectId) {
-    if (PortPresence.FREE === presence)
+    if (PortPresence.FREE === presence) {
         return WakeAction.SPAWN;
-    if (PortPresence.DAEMON !== presence)
+    }
+    if (PortPresence.DAEMON !== presence) {
         return WakeAction.REFUSE;
+    }
     return adoptable(daemonProjectId, callerProjectId) ? WakeAction.USE : WakeAction.REFUSE;
 }

package/dist/command/daemon/win32-escape.d.ts

@@ -0,0 +1,32 @@
+/** What the launcher must start. */
+export interface EscapeRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly logPath: string;
+    /** The spec file. The launcher writes the daemon pid to `<specPath>.pid`. */
+    readonly specPath: string;
+}
+/**
+ * `launched: false` means nothing started, so the caller can start the daemon another way.
+ * `launched: true` with no pid means a daemon may start, but its pid is not known in time.
+ */
+export type EscapeResult = {
+    launched: false;
+} | {
+    launched: true;
+    pid?: number;
+};
+/**
+ * The launcher, as `node -e` source. It has no double quote and no backslash, so it passes as one
+ * Windows argument in double quotes. Its one argument is the spec path.
+ */
+export declare const JOB_ESCAPE_LAUNCHER: string;
+/** The PowerShell script: start the launcher through WMI, then wait for the pid file. */
+export declare function wmiScript(request: EscapeRequest): string;
+/**
+ * Start `request` through WMI. Never throws: every failure reads as `launched: false`, unless the
+ * launcher already claimed the spec, which means it is starting the daemon.
+ */
+export declare function escapeJobViaWmi(request: EscapeRequest, run?: (script: string) => void): EscapeResult;

package/dist/command/daemon/win32-escape.js

@@ -0,0 +1,119 @@
+/**
+ * Start the daemon outside the Windows Job Object of the process that starts it.
+ *
+ * A child of `spawn(..., { detached: true })` stays in the job of its parent. An agent host can run
+ * `reticle mcp` in a job with KILL_ON_JOB_CLOSE, and the close of that job then kills the daemon
+ * too. A process that WMI `Win32_Process.Create` starts is in no job of ours.
+ *
+ * WMI cannot give the new process our stdio or our env. So WMI starts a small launcher, and the
+ * launcher does the same detached spawn as `spawnDaemon`: stdout and stderr go to the daemon log,
+ * opened for append, and the env is ours. The daemon is a child of the launcher, so it is outside
+ * the job too. The launcher reads the spawn spec from a file and writes the daemon pid to a file.
+ *
+ * The spec file is also the lock between the launcher and the fallback. The launcher claims it with
+ * a rename before it starts anything. The parent removes it after the WMI call. Only one of the two
+ * can win. If the parent wins, nothing started and the detached fallback is safe.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+/**
+ * The launcher, as `node -e` source. It has no double quote and no backslash, so it passes as one
+ * Windows argument in double quotes. Its one argument is the spec path.
+ */
+export const JOB_ESCAPE_LAUNCHER = [
+    "const fs=require('fs'),cp=require('child_process');",
+    "const f=process.argv[1],t=f+'.taken';",
+    'fs.renameSync(f,t);',
+    "const s=JSON.parse(fs.readFileSync(t,'utf8'));",
+    'fs.unlinkSync(t);',
+    "const fd=fs.openSync(s.log,'a');",
+    "const c=cp.spawn(s.command,s.args,{cwd:s.cwd,env:s.env,detached:true,stdio:['ignore',fd,fd]});",
+    "c.on('error',()=>{});",
+    'c.unref();',
+    "fs.writeFileSync(f+'.tmp',String(c.pid));",
+    "fs.renameSync(f+'.tmp',f+'.pid');",
+].join('');
+const PID_SUFFIX = '.pid';
+/** How long the script waits for the launcher to report the daemon pid. */
+const PID_WAIT_MS = 5000;
+/** A hard limit on the whole PowerShell call: its start, the WMI call and the pid wait. */
+const WMI_CALL_TIMEOUT_MS = 8000;
+const POWERSHELL = 'powershell.exe';
+const ENCODING_UTF16LE = 'utf16le';
+/** A PowerShell single-quoted literal. */
+function psLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+/** The PowerShell script: start the launcher through WMI, then wait for the pid file. */
+export function wmiScript(request) {
+    const commandLine = `"${request.command}" -e "${JOB_ESCAPE_LAUNCHER}" "${request.specPath}"`;
+    const pidPath = `${request.specPath}${PID_SUFFIX}`;
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        // SW_HIDE, so the launcher opens no console window.
+        '$startup = New-CimInstance -CimClass (Get-CimClass -ClassName Win32_ProcessStartup) -ClientOnly -Property @{ ShowWindow = [uint16]0 }',
+        `$null = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = ${psLiteral(commandLine)}; CurrentDirectory = ${psLiteral(request.cwd)}; ProcessStartupInformation = $startup }`,
+        `$deadline = (Get-Date).AddMilliseconds(${PID_WAIT_MS})`,
+        `while (-not (Test-Path -LiteralPath ${psLiteral(pidPath)}) -and (Get-Date) -lt $deadline) { Start-Sleep -Milliseconds 50 }`,
+    ].join('\n');
+}
+function runPowerShell(script) {
+    execFileSync(POWERSHELL, [
+        '-NoProfile',
+        '-NonInteractive',
+        '-EncodedCommand',
+        Buffer.from(script, ENCODING_UTF16LE).toString('base64'),
+    ], { stdio: 'ignore', timeout: WMI_CALL_TIMEOUT_MS, windowsHide: true });
+}
+function removeIfPresent(path) {
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLauncherPid(pidPath) {
+    try {
+        const pid = parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Start `request` through WMI. Never throws: every failure reads as `launched: false`, unless the
+ * launcher already claimed the spec, which means it is starting the daemon.
+ */
+export function escapeJobViaWmi(request, run = runPowerShell) {
+    const pidPath = `${request.specPath}${PID_SUFFIX}`;
+    try {
+        removeIfPresent(pidPath);
+        writeFileSync(request.specPath, JSON.stringify({
+            command: request.command,
+            args: request.args,
+            cwd: request.cwd,
+            env: request.env,
+            log: request.logPath,
+        }), 
+        // The spec holds the env. Only the user may read it, and it lives until the launcher reads it.
+        { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        return { launched: false };
+    }
+    try {
+        run(wmiScript(request));
+    }
+    catch {
+        // PowerShell missing, blocked, failed or timed out. The spec says whether the launcher ran.
+    }
+    if (removeIfPresent(request.specPath)) {
+        return { launched: false };
+    }
+    const pid = readLauncherPid(pidPath);
+    removeIfPresent(pidPath);
+    return pid === undefined ? { launched: true } : { launched: true, pid };
+}

package/dist/command/setup/agent-configs.d.ts

@@ -40,6 +40,15 @@ export interface PlatformPaths {
     readonly linux: string;
     readonly win32: string;
 }
+/**
+ * The `PlatformPaths` row to plan for on a host that reports `platform`.
+ *
+ * Casting `process.platform` to the three keys broke on every other platform Node reports: on
+ * `android` (Termux), `freebsd` or `openbsd` the row lookup returned `undefined`, `join` threw
+ * `ERR_INVALID_ARG_TYPE`, and `init` stopped after the wiring and before the dev server. Each of
+ * those keeps a Unix home layout, so they plan with the `linux` paths.
+ */
+export declare const platformKey: (platform: NodeJS.Platform) => keyof PlatformPaths;
 interface AgentClient {
     readonly id: string;
     readonly name: string;

package/dist/command/setup/agent-configs.js

@@ -39,6 +39,15 @@ const MCP_SUBCOMMAND = 'mcp';
 const RETICLE_KEY = 'reticle';
 /** The stdio entry, in the shape most clients expect. */
 const STDIO = { command: NPX, args: [SERVER_PACKAGE, MCP_SUBCOMMAND] };
+/**
+ * The `PlatformPaths` row to plan for on a host that reports `platform`.
+ *
+ * Casting `process.platform` to the three keys broke on every other platform Node reports: on
+ * `android` (Termux), `freebsd` or `openbsd` the row lookup returned `undefined`, `join` threw
+ * `ERR_INVALID_ARG_TYPE`, and `init` stopped after the wiring and before the dev server. Each of
+ * those keeps a Unix home layout, so they plan with the `linux` paths.
+ */
+export const platformKey = (platform) => 'darwin' === platform || 'win32' === platform ? platform : 'linux';
 const VSCODE_USER = {
     darwin: 'Library/Application Support/Code/User',
     linux: '.config/Code/User',

package/dist/command/setup/auto-approve.d.ts

@@ -20,9 +20,10 @@
  *    the in-app step to take instead. Nothing is written at all for an agent that is not installed:
  *    an absent agent has no Accept button to remove.
  *
- * Codex is absent by design: its approval policy is global (`approval_policy`), so there is no
- * reticle-shaped rule to write, and its config is TOML, which this repo never rewrites. Its
- * headless form, `codex exec`, does not prompt at all — which is the form the drive uses.
+ * Codex has a per-server rule, `default_tools_approval_mode`, in the `[mcp_servers.reticle]` table
+ * that `codex mcp add` writes. Its config is TOML, which this repo does not reformat: the grant adds
+ * one line under our own table header and changes no other line. When that header is not there in
+ * its plain form, nothing is written and the setting is named instead.
  */
 import { type PlatformPaths } from './agent-configs.js';
 import type { AgentWriterIo } from './agent-writer.js';
@@ -43,6 +44,12 @@ export interface ApprovalGrant {
      * a grant is only ever merged into a file the user already owns, never created.
      */
     readonly supersedesInApp?: boolean;
+    /**
+     * For a config that is not JSON: the new text, or null when the edit is not safe. Then nothing is
+     * written and `manual` tells the user what to add.
+     */
+    readonly editText?: (current: string) => string | null;
+    readonly manual?: (file: string) => string;
 }
 export declare const APPROVAL_GRANTS: readonly ApprovalGrant[];
 export declare const ApprovalOutcome: {

package/dist/command/setup/auto-approve.js

@@ -20,9 +20,10 @@
  *    the in-app step to take instead. Nothing is written at all for an agent that is not installed:
  *    an absent agent has no Accept button to remove.
  *
- * Codex is absent by design: its approval policy is global (`approval_policy`), so there is no
- * reticle-shaped rule to write, and its config is TOML, which this repo never rewrites. Its
- * headless form, `codex exec`, does not prompt at all — which is the form the drive uses.
+ * Codex has a per-server rule, `default_tools_approval_mode`, in the `[mcp_servers.reticle]` table
+ * that `codex mcp add` writes. Its config is TOML, which this repo does not reformat: the grant adds
+ * one line under our own table header and changes no other line. When that header is not there in
+ * its plain form, nothing is written and the setting is named instead.
  */
 import { joinFor, parentOf } from './agent-configs.js';
 const RETICLE_KEY = 'reticle';
@@ -41,6 +42,26 @@ function addToList(current, outer, key, value) {
     const next = { ...scope, [key]: [...list, value] };
     return null === outer ? next : { ...current, [outer]: next };
 }
+const CODEX_RULE = 'default_tools_approval_mode = "approve"';
+const CODEX_TABLE = new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*(?:${RETICLE_KEY}|"${RETICLE_KEY}"|'${RETICLE_KEY}')\\s*\\]\\s*(?:#.*)?$`);
+const CODEX_MODE_KEY = /^\s*default_tools_approval_mode\s*=/;
+const TOML_HEADER = /^\s*\[/;
+/** One line under our `[mcp_servers.reticle]` header. A mode the user set is kept. */
+function codexApprove(current) {
+    const eol = current.includes('\r\n') ? '\r\n' : '\n';
+    const lines = current.split(/\r?\n/);
+    const at = lines.findIndex((line) => CODEX_TABLE.test(line));
+    if (at < 0) {
+        return null;
+    }
+    const next = lines.findIndex((line, i) => i > at && TOML_HEADER.test(line));
+    const table = lines.slice(at + 1, next < 0 ? undefined : next);
+    if (table.some((line) => CODEX_MODE_KEY.test(line))) {
+        return current;
+    }
+    lines.splice(at + 1, 0, CODEX_RULE);
+    return lines.join(eol);
+}
 export const APPROVAL_GRANTS = [
     {
         id: 'claude-code',
@@ -98,6 +119,16 @@ export const APPROVAL_GRANTS = [
             return { ...c, mcpServers: { ...servers, [RETICLE_KEY]: { ...entry, trust: true } } };
         },
     },
+    {
+        id: 'codex',
+        name: 'Codex',
+        paths: home('.codex/config.toml'),
+        markers: [home('.codex')],
+        rule: `mcp_servers.${RETICLE_KEY}.${CODEX_RULE}`,
+        grant: (c) => c,
+        editText: codexApprove,
+        manual: (file) => `add \`${CODEX_RULE}\` under [mcp_servers.${RETICLE_KEY}] in ${file}. Without it, Codex asks before every reticle tool call, and refuses each one under approval_policy = "never".`,
+    },
 ];
 export const ApprovalOutcome = {
     GRANTED: 'granted',
@@ -123,6 +154,23 @@ export function grantAutoApproval(io, where, grants = APPROVAL_GRANTS) {
             return { ...base, outcome: ApprovalOutcome.ABSENT };
         try {
             const existed = io.exists(file);
+            if (grant.editText !== undefined) {
+                const current = existed ? io.readFile(file) : '';
+                const next = grant.editText(current);
+                if (null === next) {
+                    const warn = grant.manual?.(file);
+                    return {
+                        ...base,
+                        outcome: ApprovalOutcome.DEFERRED,
+                        ...(warn === undefined ? {} : { warn }),
+                    };
+                }
+                if (next === current) {
+                    return { ...base, outcome: ApprovalOutcome.ALREADY };
+                }
+                io.writeFile(file, next);
+                return { ...base, outcome: ApprovalOutcome.GRANTED };
+            }
             if (true === grant.supersedesInApp && !existed) {
                 return {
                     ...base,

package/dist/command/setup/bringup/dev-server-files.d.ts

@@ -13,15 +13,7 @@ declare const HandedOverSchema: z.ZodObject<{
     pid: z.ZodNumber;
     url: z.ZodString;
     appDir: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    url: string;
-    pid: number;
-    appDir: string;
-}, {
-    url: string;
-    pid: number;
-    appDir: string;
-}>;
+}, z.core.$strip>;
 export type HandedOver = z.infer<typeof HandedOverSchema>;
 /**
  * Written when `init` leaves a server running, so the next `init` can attach to it.

package/dist/command/setup/bringup/dev-server-wait.js

@@ -52,7 +52,11 @@ export function judgeWait(facts) {
  */
 const CRA_PORT_BUSY = /Something is already running on port (\d+)/i;
 const NAMED_PORT_BUSY = /Port (\d+) is (?:already )?in use/i;
-const EADDRINUSE_PORT = /(?:EADDRINUSE|address already in use)[^\d]*(\d+)/i;
+// Node prints `address already in use <address>:<port>`; the port sits after the last colon of the
+// address, so the first digit can belong to the host (`0.0.0.0:3000` said port 0, #1846). The scan
+// also stops at the line end: the stack frame under the error (`at Server (node:net:1817:16)`)
+// carries digits of its own, and they are not the port.
+const EADDRINUSE_PORT = /(?:EADDRINUSE|address already in use)[^\d\n]*(?:.*:)?(\d+)/i;
 export function portBusyMessage(output) {
     const match = CRA_PORT_BUSY.exec(output) ?? NAMED_PORT_BUSY.exec(output) ?? EADDRINUSE_PORT.exec(output);
     const port = match?.[1];

package/dist/command/setup/bringup/ensure-daemon.js

@@ -19,11 +19,11 @@
  * `bridge-port.ts`.
  */
 import { log } from '../../../log.js';
-import { isAlive, readPid, reticleStateHome, spawnDaemon } from '../../daemon/daemon.js';
+import { isAlive, reticleStateHome, spawnDaemon } from '../../daemon/daemon.js';
 import { readDaemonRegistry } from '../../daemon/daemon-resolve.js';
 import { LOOPBACK_HOST, STATUS_HOLD_MS } from '@reticlehq/core';
 import { probePresence, presenceIsUsable } from '../../daemon/binding/port-presence.js';
-import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
+import { daemonProcessAlive, probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
 import { daemonSpawnArgs, headlessByDefault } from '../../cli/daemon-start-options.js';
 import { fetchStatus, summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { runKill } from '../../cli/cli-kill.js';
@@ -76,7 +76,7 @@ export async function ensureDaemon(port, deps) {
                 message: `The Reticle daemon on port ${String(port)} is ${theirs}, which speaks a different wire ` +
                     `contract than this init, so it will refuse your app — and ` +
                     `${String(sessionCount)} session(s) are still using it, so init will not stop it. When ` +
-                    `they are done, run \`npx @reticlehq/server kill --port ${String(port)}\` and re-run init.`,
+                    `they are done, run \`npx @reticlehq/server stop --force --port ${String(port)}\` and re-run init.`,
             };
         }
         if (!(await deps.replace(port)))
@@ -168,10 +168,7 @@ export function nodeEnsureDaemonDeps(skewed) {
                 log('reticle_setup_daemon_started', { port, started });
             return started;
         },
-        starting: (port) => {
-            const pid = readPid(port);
-            return null !== pid && isAlive(pid);
-        },
+        starting: daemonProcessAlive,
         // The same wait `reticle restart` does: poll until `/status` answers as a daemon, bounded. A
         // cold daemon on a fresh HOME outlived the proxy's shorter reconnect budget this used to borrow.
         waitReady: async (port) => {

package/dist/command/setup/init/init-host.js

@@ -1,4 +1,6 @@
+import { homedir } from 'node:os';
 import { spanSync } from '../../../trace.js';
+import { hookBinFor } from '../../cli/hook/hook-fast.js';
 import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 import { reportOnboardingStep } from '../../../telemetry/onboarding-funnel.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
@@ -38,6 +40,10 @@ export function serverInitHost() {
         },
         // Claude Code marks every process it spawns. If the marker ever changes, init falls back to the
         // notice it printed before, which is the safe direction.
+        /** This CLI's own bin, so the agent hooks run it with node instead of paying npx's start. */
+        hookBin() {
+            return hookBinFor(homedir(), process.platform);
+        },
         insideClaudeCode() {
             return CLAUDE_CODE_MARKER_VALUE === process.env[CLAUDE_CODE_MARKER_ENV];
         },

package/dist/command/setup/init/init-port.js

@@ -58,11 +58,12 @@ dir) {
     // it recorded. Moving off it strands that agent: an MCP resolves its port once, at startup.
     if (true === deps.daemonStartedHere?.(RETICLE_DEFAULT_PORT))
         return undefined;
-    // The bridge's own rule: it refuses a page only when it has served exactly ONE other project. A
-    // daemon serving nobody, several projects, or ours accepts this one. A project that has never
-    // been through init has no id yet, so a single named holder is somebody else.
+    // A daemon that serves other projects, one or several, is somebody else's: it is rooted in their
+    // directory and linked to their cloud project, even when its bridge would accept this page. A
+    // daemon serving nobody, or this project among others, is kept. A project that has never been
+    // through init has no id yet, so every named holder is somebody else.
     const holders = await deps.daemonProjects(RETICLE_DEFAULT_PORT);
-    if (1 !== holders.length || holders[0] === projectId)
+    if (0 === holders.length || (projectId !== undefined && holders.includes(projectId)))
         return undefined;
     const seed = projectId ?? dir;
     return deps.pickPort(seed === undefined ? PROJECT_PORT_FIRST : projectPortFor(seed));

package/dist/command/setup/init/init-runtime.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { FEEDBACK_HINT, Framework, InitFailure } from '@reticlehq/init';
+import { COMMUNITY_HINT, FEEDBACK_HINT, Framework, InitFailure, } from '@reticlehq/init';
 import { confirmInstall, nodeConfirmDeps } from '../terminal/confirm.js';
 import { writeLicenseKey } from '../license-key.js';
 import { registerOtherAgents, runSetupCommand, } from '../setup-command.js';
@@ -228,6 +228,8 @@ firstFlow) {
             return undefined === devCommand ? {} : { devCommand, devCommandIsStaticPage: true };
         })(),
         ...(undefined === parsed.url ? {} : { suppliedUrl: parsed.url }),
+        // So setup can tell which port the dev server will take, before it starts one (#1377).
+        framework: context.framework,
     }, (line) => io.print(line))
         .then(async (outcome) => {
         if (result.outcome !== undefined) {
@@ -247,6 +249,8 @@ firstFlow) {
                     outcome.reachedPhase === SetupPhase.DEV_SERVER
                         ? InitFailure.DEV_SERVER
                         : InitFailure.APP_CONNECTION;
+                if (outcome.stop !== undefined)
+                    init.stop = outcome.stop;
             }
             reportOnce(init);
         }
@@ -282,12 +286,14 @@ firstFlow) {
                 io.print(`   ${String(i + 1)}. ${step}`);
             // Already spaced by the blank line above when nothing was listed.
             ask(0 < outcome.fallback.length);
+            io.print(COMMUNITY_HINT);
             return;
         }
         if (outcome.ok) {
             io.print(`✓ setup complete — ${outcome.url ?? 'the app'} is instrumented and its first flow is ` +
                 'saved. The tab stays open; a linked project sends the flow and its run to your dashboard.');
             ask();
+            io.print(COMMUNITY_HINT);
             return;
         }
         // A run that produced no verdict did not succeed, and the exit code is the one place a caller

package/dist/command/setup/node-effects.d.ts

@@ -13,6 +13,14 @@
  */
 import type { CandidateSession } from './session-pick.js';
 import type { PageProbe } from './probe/page-probe.js';
+/**
+ * The state home when this process can write it, else the project's own `.reticle/logs`.
+ *
+ * A sandboxed agent host or a locked-down profile cannot write the state home. Init had already
+ * wired the project by then, so a log folder must not be the reason it stops. The caller prints the
+ * log path, so the fallback is never silent.
+ */
+export declare function writableLogDir(preferred: string, projectDir: string): string;
 /** The dev server this process started, and the only one it will ever stop. */
 export declare class OwnedDevServer {
     private readonly logDir;

package/dist/command/setup/node-effects.js

@@ -12,9 +12,10 @@
  * listening indefinitely.
  */
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { accessSync, constants as fsConstants, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ReticleDir } from '@reticlehq/core';
 import { isAlive } from '../daemon/daemon.js';
 import { DEV_SERVER_LOG_CAP_BYTES, ROTATED_SUFFIX } from './bringup/dev-server-log-cap.js';
 import { devServerLogName, recordHandOver, sweepDeadDevServers, } from './bringup/dev-server-files.js';
@@ -29,6 +30,37 @@ const ASTRO_DEV_BACKGROUND_ENV = 'ASTRO_DEV_BACKGROUND';
 const PROBE_TIMEOUT_MS = 5_000;
 /** The supervisor that owns the server's output and keeps its log bounded. */
 const LOG_CAP_SCRIPT = fileURLToPath(new URL('./bringup/dev-server-log-cap.js', import.meta.url));
+/** The error code of a `wx` write to a file that is already there. */
+const EEXIST = 'EEXIST';
+/**
+ * The state home when this process can write it, else the project's own `.reticle/logs`.
+ *
+ * A sandboxed agent host or a locked-down profile cannot write the state home. Init had already
+ * wired the project by then, so a log folder must not be the reason it stops. The caller prints the
+ * log path, so the fallback is never silent.
+ */
+export function writableLogDir(preferred, projectDir) {
+    try {
+        mkdirSync(preferred, { recursive: true });
+        accessSync(preferred, fsConstants.W_OK);
+        return preferred;
+    }
+    catch {
+        const fallback = join(projectDir, ReticleDir.ROOT, ReticleDir.LOGS_SUBDIR);
+        mkdirSync(fallback, { recursive: true });
+        // Its own ignore file, because the workspace one may not be written yet on a first init. `wx`
+        // creates it only when it is absent, in one step, so a file that is already there is kept.
+        try {
+            writeFileSync(join(fallback, '.gitignore'), '*\n', { flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== EEXIST) {
+                throw error;
+            }
+        }
+        return fallback;
+    }
+}
 /** The dev server this process started, and the only one it will ever stop. */
 export class OwnedDevServer {
     logDir;
@@ -51,11 +83,11 @@ export class OwnedDevServer {
      * dev-server-log-cap.ts. It is the process group leader, so `pid()` and `stop()` cover both.
      */
     start(command, cwd, env) {
-        mkdirSync(this.logDir, { recursive: true });
+        const logDir = writableLogDir(this.logDir, cwd);
         // Logs of servers that are gone, from every project, so the state home stops growing a file
         // per app ever started. This one's are replaced below anyway.
-        sweepDeadDevServers(this.logDir, { alive: isAlive, now: Date.now(), keep: cwd });
-        const log = join(this.logDir, devServerLogName(cwd));
+        sweepDeadDevServers(logDir, { alive: isAlive, now: Date.now(), keep: cwd });
+        const log = join(logDir, devServerLogName(cwd));
         // Unlinked rather than truncated: a previous server for this project may still hold the old
         // file open, and truncating under it would interleave its lines into this run's output.
         rmSync(log, { force: true });

package/dist/command/setup/probe/dev-port.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The port the dev server will take, when that is known: the one its script pins, else the
+ * framework's default unless the dev config names a port of its own. Undefined otherwise, and
+ * nothing is probed: a guessed port refusing a start would be a worse failure than this one.
+ */
+export declare function expectedDevPort(facts: {
+    pinned?: number | undefined;
+    framework?: string | undefined;
+    devConfig?: string | undefined;
+}): number | undefined;
+/**
+ * The one loopback something answers on at `port` while the other is free, or undefined.
+ *
+ * Only that split is refused. A port busy on both loopbacks is one the dev server sees: Vite and
+ * Next move to the next port and print it, and setup reads that, as it always has. A second Vite
+ * app on 5173 is the common case, and stopping there would break a start that works. The dev server
+ * cannot see a listener on only one loopback, because it binds the other with no error, and then
+ * `localhost` and `127.0.0.1` serve two different apps.
+ */
+export declare function loneLoopbackOnDevPort(port: number): Promise<string | undefined>;
+/** What setup says instead of starting a dev server on the other half of a split port. */
+export declare function splitDevPortNote(port: number, host: string): string;
+/** The text of every dev config present in `appDir`, joined, or undefined when there is none. */
+export declare function devConfigText(appDir: string): string | undefined;
+/** The port the project's dev script pins (`--port`, `-p`, `PORT=`), or undefined. */
+export declare function pinnedDevPort(appDir: string): number | undefined;