@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/cli/report-command.js

@@ -6,13 +6,16 @@
  * one `reticle_context` serves, so the terminal and the agent cannot be told two different stories.
  */
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { DiscoveryInvite, ReticleDir } from '@reticlehq/core';
+import { DiscoveryInvite, ReticleDir, asRecord } from '@reticlehq/core';
 import { gapSummary } from '../../judgement/runs/artifact/gap-summary.js';
 import { SessionJournal } from '../../memory/journal/session-journal.js';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
 import { gapHookLine, gapReportLines } from '../../judgement/runs/artifact/gap-report.js';
+import { DriveOrigin, DriveStatus, pollCall } from '../../features/harness/drive-runs.js';
+import { DRIVE_RECORD_SUFFIX, UNMATCHED_SUBDIR } from '../../memory/project/dir/reticle-dir.js';
 /**
  * A session last written longer ago than this is not the turn a hook is asking about.
  *
@@ -20,33 +23,99 @@ import { gapHookLine, gapReportLines } from '../../judgement/runs/artifact/gap-r
  * drive older than an hour reads as "no claim this session", which errs toward saying so.
  */
 const HOOK_WINDOW_MS = 60 * 60 * 1000;
-/** The session whose action ledger was written most recently, if any. */
-function newestSession(root) {
-    const sessionsDir = join(root, ReticleDir.SESSIONS_SUBDIR);
-    if (!existsSync(sessionsDir))
+/**
+ * How long the Stop hook keeps an agent for one Harness drive. A record still `running` after this
+ * was left by a daemon that stopped, and it would hold the agent forever.
+ *
+ * ponytail: a fixed bound from the start time, not a liveness check on the daemon. Ask the daemon
+ * when a real drive runs longer than this.
+ */
+const KEEP_ALIVE_MAX_MS = 30 * 60 * 1000;
+/** What the Stop hook tells an agent that tried to stop while its Harness drive runs. */
+export function keepAliveReason(runId) {
+    return (`The Harness drive ${runId} that you started is still running. Do not stop yet. ` +
+        `Call ${pollCall(runId)} until it ends. If it reports a failed check, fix the code, then ` +
+        `start the same drive again to verify the fix.`);
+}
+/** The newest drive this agent started that still runs, read from `.reticle/runs/`. */
+function agentDriveRunning(root, now) {
+    const runs = join(root, ReticleDir.RUNS_SUBDIR);
+    if (!existsSync(runs))
         return undefined;
     let newest;
-    for (const id of readdirSync(sessionsDir)) {
-        const ledger = join(sessionsDir, id, ReticleDir.JOURNAL_ACTIONS_FILE);
-        if (!existsSync(ledger))
+    for (const name of readdirSync(runs)) {
+        if (!name.endsWith(DRIVE_RECORD_SUFFIX))
+            continue;
+        let record;
+        try {
+            record = asRecord(JSON.parse(readFileSync(join(runs, name), 'utf8')));
+        }
+        catch {
+            continue;
+        }
+        const { harnessRun, status, origin, startedAt } = record;
+        if (DriveStatus.RUNNING !== status || DriveOrigin.AGENT !== origin)
+            continue;
+        if ('string' !== typeof harnessRun || 'number' !== typeof startedAt)
+            continue;
+        if (now - startedAt > KEEP_ALIVE_MAX_MS)
+            continue;
+        if (newest === undefined || startedAt > newest.startedAt)
+            newest = { runId: harnessRun, startedAt };
+    }
+    return newest?.runId;
+}
+/**
+ * Every `.reticle` root a session of this project can be in: the project's own, then each folder the
+ * daemon filed under `~/.reticle/unmatched` for a page it could not tie to a project (before
+ * `reticle init`). Without them the hook said "No claim was checked" after claims had held.
+ *
+ * ponytail: an unmatched folder is not tied to this cwd; the newest session in the window wins.
+ */
+function sessionRoots(root, home) {
+    if (home === undefined)
+        return [root];
+    const unmatched = join(home, ReticleDir.ROOT, UNMATCHED_SUBDIR);
+    if (!existsSync(unmatched))
+        return [root];
+    return [root, ...readdirSync(unmatched).map((name) => join(unmatched, name))];
+}
+/** The session whose action ledger was written most recently, if any. */
+function newestSession(roots) {
+    let newest;
+    for (const root of roots) {
+        const sessionsDir = join(root, ReticleDir.SESSIONS_SUBDIR);
+        if (!existsSync(sessionsDir))
             continue;
-        const writtenAt = statSync(ledger).mtimeMs;
-        if (newest === undefined || writtenAt > newest.writtenAt)
-            newest = { id, writtenAt };
+        for (const id of readdirSync(sessionsDir)) {
+            const ledger = join(sessionsDir, id, ReticleDir.JOURNAL_ACTIONS_FILE);
+            if (!existsSync(ledger))
+                continue;
+            const writtenAt = statSync(ledger).mtimeMs;
+            if (newest === undefined || writtenAt > newest.writtenAt)
+                newest = { id, writtenAt, root };
+        }
     }
     return newest;
 }
 export async function reportFor(input) {
+    const root = join(input.cwd, ReticleDir.ROOT);
+    // The one case the hook blocks: the agent's own Harness drive is still running, so its result,
+    // and any defect it finds, would reach nobody.
+    const driving = true === input.hook ? agentDriveRunning(root, input.now) : undefined;
+    if (driving !== undefined)
+        return { lines: [], block: keepAliveReason(driving) };
     if (true === input.hook && !input.treeChanged)
         return { lines: [] };
-    const root = join(input.cwd, ReticleDir.ROOT);
-    const found = input.session === undefined ? newestSession(root) : { id: input.session, writtenAt: input.now };
+    const found = input.session === undefined
+        ? newestSession(sessionRoots(root, input.home))
+        : { id: input.session, writtenAt: input.now, root };
     const current = found !== undefined && (true !== input.hook || input.now - found.writtenAt <= HOOK_WINDOW_MS)
         ? found
         : undefined;
     const actions = current === undefined
         ? []
-        : await new SessionJournal(createNodeFileSystem(), root, current.id).readActions();
+        : await new SessionJournal(createNodeFileSystem(), current.root, current.id).readActions();
     const gap = gapSummary(actions);
     if (true === input.hook) {
         const line = gapHookLine(gap);
@@ -66,16 +135,19 @@ function treeChanged(cwd) {
     }
 }
 /**
- * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0: it is
- * print-only by design, so the human sees the gap and the agent is never blocked by it.
+ * The command. As a hook it prints Claude Code's `systemMessage` shape and always exits 0, so the
+ * human sees the gap. It blocks the stop in one case only: a Harness drive the agent started is still
+ * running, bounded by `KEEP_ALIVE_MAX_MS`.
  */
 export async function handleReport(session, hook) {
     const cwd = process.cwd();
     let lines;
+    let block;
     try {
-        ({ lines } = await reportFor({
+        ({ lines, block } = await reportFor({
             cwd,
             now: Date.now(),
+            home: homedir(),
             treeChanged: hook ? treeChanged(cwd) : true,
             ...(session === undefined ? {} : { session }),
             hook,
@@ -91,6 +163,11 @@ export async function handleReport(session, hook) {
         process.exitCode = 1;
         return;
     }
+    // Claude Code and Codex both read this shape from a Stop hook: the agent goes on, told `reason`.
+    if (block !== undefined) {
+        process.stdout.write(`${JSON.stringify({ decision: 'block', reason: block })}\n`);
+        return;
+    }
     if (0 === lines.length)
         return;
     process.stdout.write(hook ? `${JSON.stringify({ systemMessage: lines.join('\n') })}\n` : `${lines.join('\n')}\n`);

package/dist/command/cli/status-fields.d.ts

@@ -1,6 +1,6 @@
 /**
- * The two optional blocks `status` adds to its payload, out of cli.ts because that file hit the
- * 1000-line cap and the rule is to split rather than raise it.
+ * `reticle status`: what it reads and reports, and the two optional blocks it adds to its payload.
+ * Out of cli.ts because that file hit the 1000-line cap and the rule is to split rather than raise it.
  *
  * They belong together: both answer "is there anything else the reader needs to know", both are
  * absent when the answer is no, and both are the reason a healthy `status` reads as healthy.
@@ -26,3 +26,10 @@ export declare function withNextAction(facts: {
 export declare function splitBrainFields(port: number, projectId: string | undefined): {
     splitBrain?: string;
 };
+/**
+ * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
+ * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
+ * transport lives on stdout), so `--json` must not go through it.
+ */
+export declare function reportStatus(fields: Record<string, unknown>, json: boolean): void;
+export declare function handleStatus(port: number, json?: boolean): Promise<void>;

package/dist/command/cli/status-fields.js

@@ -1,10 +1,22 @@
 import { statusNextAction } from './answers/status-next-action.js';
 import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
-import { isAlive, reticleStateHome } from '../daemon/daemon.js';
-import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
+import { isAlive, readPid, reticleStateHome } from '../daemon/daemon.js';
+import { hasAnyAppConnectedBefore, hasProjectConnectedBefore, } from '../../memory/recall/prior/connection-memory.js';
+import { devServersForProject } from '@reticlehq/core';
+import { readDevServers } from '../daemon/dev-servers.js';
+import { attachStatusFields } from '../../surface/mcp/attach-memory.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { availableUpdate } from '../update/update-nudge.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/binding/port-presence.js';
+import { summarizeStatus } from './launch/cli-launch.js';
+import { readProjectId } from './ports/resolve/cli-port.js';
+import { accountStatusFields } from './cloud-cli.js';
+import { localLinkOf, workspaceAppLinks } from './status/workspace-links.js';
+import { statusLines } from './status/status-lines.js';
 /**
- * The two optional blocks `status` adds to its payload, out of cli.ts because that file hit the
- * 1000-line cap and the rule is to split rather than raise it.
+ * `reticle status`: what it reads and reports, and the two optional blocks it adds to its payload.
+ * Out of cli.ts because that file hit the 1000-line cap and the rule is to split rather than raise it.
  *
  * They belong together: both answer "is there anything else the reader needs to know", both are
  * absent when the answer is no, and both are the reason a healthy `status` reads as healthy.
@@ -27,3 +39,135 @@ export function splitBrainFields(port, projectId) {
     const note = elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
     return note === undefined ? {} : { splitBrain: note };
 }
+/**
+ * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
+ * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
+ * transport lives on stdout), so `--json` must not go through it.
+ */
+export function reportStatus(fields, json) {
+    if (json) {
+        const line = JSON.stringify({
+            t: new Date().toISOString(),
+            event: 'reticle_status',
+            ...fields,
+        });
+        process.stdout.write(`${line}\n`);
+        return;
+    }
+    process.stdout.write(`${statusLines(fields).join('\n')}\n`);
+}
+export async function handleStatus(port, json = false) {
+    // A broken session file must not cost the reader the rest of the status.
+    const account = await accountStatusFields().catch(() => ({}));
+    // At a workspace root that is no app of its own, each app and its link: "not linked" named none.
+    const linked = account.linkedProject;
+    if ('string' !== typeof linked && readProjectId(process.cwd()) === undefined) {
+        Object.assign(account, {
+            workspaceApps: await workspaceAppLinks(process.cwd(), localLinkOf).catch(() => []),
+        });
+    }
+    const report = (fields) => reportStatus({ ...fields, ...account }, json);
+    const pid = readPid(port);
+    // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
+    const projectId = readProjectId(process.cwd());
+    const previouslyConnected = hasAnyAppConnectedBefore(reticleStateHome(), port, projectId);
+    // The narrow twin. Every sentence that says "this project", and the decision about whether THIS
+    // app is instrumented, needs the question the wide one cannot answer without a project id.
+    const projectPreviouslyConnected = hasProjectConnectedBefore(reticleStateHome(), port, projectId);
+    // Whether `init` has run HERE. Registering the MCP server does not wire the app, and more than one
+    // path does the first without the second — so this is the commonest reason `status` has nothing to
+    // report, and it was not among the facts this command could state.
+    const initialized = projectId !== undefined;
+    // The OTHER half of the install, and the half this command could not see. A host that registers
+    // Reticle and never lists its tools looks exactly like an abandoned install from here — same idle
+    // daemon, same zero sessions — and the user sees a tool that does nothing. See attach-memory.ts.
+    const client = attachStatusFields(reticleStateHome(), port);
+    // What the dev servers themselves said. The reason this command could previously only guess at
+    // whether the app was running is that it had no way to see one; now the ones carrying Reticle
+    // announce, and the advice below stops contradicting the terminal the reader is looking at.
+    // Scoped to THIS project: the registry is machine-wide, and an unrelated app's dev server must
+    // not make this project look like it is running.
+    const devServerPorts = devServersForProject(readDevServers(reticleStateHome()), {
+        projectId,
+        root: process.cwd(),
+    }).map((d) => d.port);
+    // The failure where every individual check is green and the chain is broken: the agent's proxy and
+    // the app resolved their ports independently and landed on two different daemons. Reported from
+    // BOTH stances, because neither one can see it alone.
+    const split = splitBrainFields(port, projectId);
+    // Doctor and status must answer the same liveness question. A live pid only says that some
+    // process exists; a Reticle daemon is running only when the shared port probe reaches /status.
+    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+    if (!presenceIsUsable(presence)) {
+        report({
+            port,
+            running: false,
+            presence,
+            ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
+            // `init` promises this command says why the app has not connected. Without it the answer was
+            // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
+            // just a daemon that has not been asked to do anything yet.
+            ...withNextAction({
+                running: false,
+                sessionCount: 0,
+                previouslyConnected,
+                projectPreviouslyConnected,
+                initialized,
+                devServerPorts,
+            }),
+            ...client,
+            ...split,
+        });
+        return;
+    }
+    // The daemon answered the same probe doctor trusts — ask it for live sessions + health.
+    const payload = await fetchStatus(port);
+    // `status` is the second-most-run command and the one a HUMAN types. The update nudge otherwise
+    // only rides a tool result, which the majority of daemons never produce — so the people most in
+    // need of an upgrade were the ones with no path to hearing about it.
+    const update = availableUpdate();
+    const nudge = update === undefined ? {} : { updateAvailable: update };
+    if (payload === undefined) {
+        report({
+            port,
+            running: true,
+            pid,
+            ...nudge,
+            ...withNextAction({
+                running: true,
+                sessionCount: 0,
+                previouslyConnected,
+                projectPreviouslyConnected,
+                initialized,
+                devServerPorts,
+            }),
+            ...client,
+            ...split,
+        });
+        return;
+    }
+    const summary = summarizeStatus(payload);
+    // Only when the daemon did NOT already explain itself. It has the whole diagnosis in-process and
+    // puts it on the wire as `why`; printing a second, thinner opinion beside it risks two confident
+    // answers pointing different ways, which is worse than one.
+    const next = summary.why === undefined
+        ? withNextAction({
+            running: true,
+            ...summary,
+            previouslyConnected,
+            projectPreviouslyConnected,
+            initialized,
+            devServerPorts,
+        })
+        : {};
+    report({
+        port,
+        running: true,
+        pid,
+        ...summary,
+        ...next,
+        ...client,
+        ...split,
+        ...nudge,
+    });
+}

package/dist/command/cli/try-command.d.ts

@@ -1,6 +1,6 @@
 import type { CloudConfig } from '../../memory/cloud/cloud-sync.js';
 import { type FreeDrive } from '../../features/harness/platform/platform-drives.js';
-export declare const MSG_SIGN_IN_FIRST = "Sign in first: reticle connect (it is free, no card)";
+export declare const MSG_SIGN_IN_FIRST = "Link this folder first: reticle connect. It signs you in if you are not, and it is free, no card.";
 /** The whole drive, model turns and browser included, before the CLI stops waiting for it. */
 export declare const TRY_BUDGET_MS = 120000;
 /** Model turns in the one free drive. Bounds what it costs, not what it may find. */
@@ -53,8 +53,7 @@ export declare function cmdTry(argv: readonly string[], cloudCommands: TryCloud)
 /**
  * How `init` ends once the connection is proved: what Reticle sees of the app, what it is missing,
  * and the prompt that hands the rest to the coding agent, which proves the first flow. `init` never
- * drives: the Harness is opt-in and unlocks at a coverage score (core's `instrumentation-coverage.ts`), and a
- * freshly wired app is rarely there yet.
+ * drives: the Harness is opt-in. It runs at any setup score.
  *
  * Read from the daemon's `/status`, the same coverage `doctor` prints, so the two never disagree.
  */
@@ -64,7 +63,7 @@ export declare const UNLINKED_PITCH: string[];
 export declare const msgProveOneFlow: (url: string) => string;
 /**
  * The closing lines for one tab's coverage, as `/status` reports it: the score, what is missing, the
- * Harness gate in its own sentence, and the prompt for the coding agent. Pure.
+ * Harness switch, and the prompt for the coding agent. Pure.
  */
 export declare function initCoverageLines(tab: Record<string, unknown> | undefined, url: string): string[];
 /**

package/dist/command/cli/try-command.js

@@ -27,7 +27,7 @@ import { callerArtifactRoot } from '../../memory/project/link-directory.js';
 import { seeRunLine } from '../../memory/project/sync-status.js';
 import { DAEMON_INNER_COMMAND, PORT_FLAG } from './cli-parse.js';
 import { acquireLease, connectOverSse, endpointFor, exploreToEnd, refusalText, releaseLease, verdictOf, } from './adhoc-verdict.js';
-export const MSG_SIGN_IN_FIRST = 'Sign in first: reticle connect (it is free, no card)';
+export const MSG_SIGN_IN_FIRST = 'Link this folder first: reticle connect. It signs you in if you are not, and it is free, no card.';
 const PERSONA_FLAG = '--persona';
 /** The whole drive, model turns and browser included, before the CLI stops waiting for it. */
 export const TRY_BUDGET_MS = 120_000;
@@ -263,15 +263,14 @@ export async function cmdTry(argv, cloudCommands) {
 /**
  * How `init` ends once the connection is proved: what Reticle sees of the app, what it is missing,
  * and the prompt that hands the rest to the coding agent, which proves the first flow. `init` never
- * drives: the Harness is opt-in and unlocks at a coverage score (core's `instrumentation-coverage.ts`), and a
- * freshly wired app is rarely there yet.
+ * drives: the Harness is opt-in. It runs at any setup score.
  *
  * Read from the daemon's `/status`, the same coverage `doctor` prints, so the two never disagree.
  */
 /** What a project that is not linked is told, once, at the end. */
 export const UNLINKED_PITCH = [
     'Results stay on this machine. `reticle connect` saves them to your dashboard and lets Reticle',
-    'Harness test the whole app: a new account gets 10 free credits.',
+    'Harness test the whole app: a new account gets free credits to start.',
 ];
 /** Prove one flow with the coding agent: the line every ending names. */
 export const msgProveOneFlow = (url) => `Then ask your coding agent: "Use Reticle to prove one flow in ${url}: drive it, and end with ` +
@@ -286,25 +285,21 @@ const names = (value) => Array.isArray(value)
     : [];
 /**
  * The closing lines for one tab's coverage, as `/status` reports it: the score, what is missing, the
- * Harness gate in its own sentence, and the prompt for the coding agent. Pure.
+ * Harness switch, and the prompt for the coding agent. Pure.
  */
 export function initCoverageLines(tab, url) {
-    const gate = asRecord(tab?.['harnessGate']);
-    const percent = gate['percent'];
+    const percent = tab?.['setupScore'];
     if (tab === undefined || 'number' !== typeof percent)
         return [
             'Instrumentation is measured on an open tab of the app: run `reticle doctor` with it open.',
             msgProveOneFlow(url),
         ];
     const unseen = [...names(tab['missing']), ...names(tab['notSeenYet'])];
-    const reason = gate['reason'];
     const prompt = tab['prompt'];
     return [
         `Instrumentation: ${String(percent)}%` +
             (0 === unseen.length ? '' : ` — missing: ${unseen.join(', ')}`),
-        'string' === typeof reason
-            ? reason
-            : `Harness can be switched on: it is off until you switch it on in the HUD's Settings.`,
+        `Harness can be switched on: it is off until you switch it on in the HUD's Settings.`,
         ...('string' === typeof prompt
             ? [
                 'Paste this into your coding agent; it closes the gaps and proves the first flow:',

package/dist/command/cli/verify-results.d.ts

@@ -9,11 +9,14 @@ import { Verified, type ReticleVerificationRun } from '@reticlehq/core';
 type JourneyVerdict = typeof Verified.YES | typeof Verified.NO | typeof Verified.UNKNOWN;
 export interface VerifyResults {
     verdict: JourneyVerdict;
+    /** `runId` is the run the journey came from, set only when that run reached the platform. */
     results: {
         journey: string;
         verdict: JourneyVerdict;
         reason?: string;
+        runId?: string;
     }[];
 }
-export declare function verifyResults(run: ReticleVerificationRun): VerifyResults;
+/** `pushed`: the run reached the platform, so its id resolves there and the results name it. */
+export declare function verifyResults(run: ReticleVerificationRun, pushed?: boolean): VerifyResults;
 export {};

package/dist/command/cli/verify-results.js

@@ -14,11 +14,13 @@ function journeyVerdict(status) {
         return Verified.YES;
     return Verified.UNKNOWN;
 }
-export function verifyResults(run) {
+/** `pushed`: the run reached the platform, so its id resolves there and the results name it. */
+export function verifyResults(run, pushed = false) {
     const results = run.flows.map((flow) => ({
         journey: flow.name,
         verdict: journeyVerdict(flow.status),
         ...(flow.failureReason === undefined ? {} : { reason: flow.failureReason }),
+        ...(pushed ? { runId: run.runId } : {}),
     }));
     const verdict = results.some((r) => Verified.NO === r.verdict)
         ? Verified.NO

package/dist/command/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+export { handleStatus, reportStatus } from './cli/status-fields.js';
 import { parseCliArgs, CLI_USAGE } from './cli/cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli/cli-parse.js';
@@ -16,11 +17,4 @@ export declare function connectExit(cloudCode: number, initUnfinished: string |
     code: number;
     note?: string;
 };
-/**
- * Report status to the terminal. `--json` writes one structured line to STDOUT so it can be piped
- * into `jq`; the human-readable block goes to stdout too. `log()` stays on stderr (the MCP
- * transport lives on stdout), so `--json` must not go through it.
- */
-export declare function reportStatus(fields: Record<string, unknown>, json: boolean): void;
-export declare function handleStatus(port: number, json?: boolean): Promise<void>;
 export declare function main(): void;