@reticlehq/server 3.5.0 → 3.6.0

package/dist/portal/session/first-run-wiring.d.ts

@@ -0,0 +1,42 @@
+export interface WiredStep {
+    mark: string;
+    title: string;
+    target: string;
+}
+export interface WireOutcome {
+    ok: boolean;
+    /** Where init ran. */
+    directory: string;
+    /** Every step of init's plan, applied or not, as it printed them. */
+    steps: WiredStep[];
+    /** The app's url, when init got as far as the dev server. */
+    url?: string;
+    /** Why it stopped, in init's words or ours. */
+    error?: string;
+}
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type RunCli = (args: readonly string[], cwd: string) => Promise<RunResult>;
+export interface FirstRunWiring {
+    /**
+     * The directory init would run in, or undefined when it cannot be told without guessing: a
+     * daemon started in the home directory or at a filesystem root has no project of its own.
+     */
+    projectDirectory(cwd: string): string | undefined;
+    wire(directory: string): Promise<WireOutcome>;
+}
+export declare function projectDirectoryOf(cwd: string, home?: string, wired?: (dir: string) => boolean): string | undefined;
+/** init's plan lines, and the one JSON object it prints last under `--json`. */
+export declare function readInitOutput(stdout: string): {
+    steps: WiredStep[];
+    result: unknown;
+};
+export declare function firstRunWiring(options: {
+    /** This daemon's port, so init wires the app to it rather than choosing another. */
+    port: number;
+    cliPath: string;
+    run?: RunCli;
+}): FirstRunWiring;

package/dist/portal/session/first-run-wiring.js

@@ -0,0 +1,132 @@
+/**
+ * Wiring the app the first time an agent needs it, instead of at installation.
+ *
+ * Installing Reticle puts a CLI and an MCP server on the machine and touches no project. The app is
+ * instrumented the first time an agent actually uses Reticle against it: the daemon runs its own
+ * CLI's `init` in the project directory, the same codemod, dev-server start and connect a person
+ * would have run by hand, and reports what it changed.
+ *
+ * A child process rather than an import: the daemon never imports `@reticlehq/init`
+ * (library-path-boundary.test.ts), and running the CLI keeps that line where it is.
+ *
+ * Once per directory for the life of the daemon. A second call returns the first answer, so an agent
+ * that asks again after a failure is told the same thing rather than re-running a codemod on files
+ * the first run already changed.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { isWebApp } from '@reticlehq/init';
+import { readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+/** init has a dev server to start and a page to wait for; past this it is not coming. */
+const WIRE_TIMEOUT_MS = 120_000;
+/** A plan line as init prints it: `[✓] Vite plugin → vite.config.ts`. */
+const PLAN_LINE = /^\s*\[(.)\]\s+(.+?)\s+→\s+(.+)$/;
+export function projectDirectoryOf(cwd, home = homedir(), wired = (dir) => readProjectId(dir) !== undefined) {
+    const dir = resolve(cwd);
+    if (dir === resolve(home) || dir === resolve('/'))
+        return undefined;
+    // Already wired: nothing for a first run to do, and init over a wired app proves nothing.
+    if (wired(dir))
+        return undefined;
+    // Only an app with a page: a daemon started in a library or API package wrote a config there.
+    return isWebApp('.', {
+        exists: (p) => existsSync(join(dir, p)),
+        readFile: (p) => {
+            try {
+                return readFileSync(join(dir, p), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+    })
+        ? dir
+        : undefined;
+}
+/** init's plan lines, and the one JSON object it prints last under `--json`. */
+export function readInitOutput(stdout) {
+    const steps = stdout
+        .split('\n')
+        .map((line) => PLAN_LINE.exec(line))
+        .flatMap((m) => null === m
+        ? []
+        : [{ mark: m[1] ?? '', title: (m[2] ?? '').trim(), target: (m[3] ?? '').trim() }]);
+    const at = stdout.lastIndexOf('\n{\n') + 1;
+    let result;
+    try {
+        result = JSON.parse(stdout.slice(at));
+    }
+    catch {
+        result = undefined;
+    }
+    return { steps, result };
+}
+function nodeRun(cliPath) {
+    return (args, cwd) => new Promise((done) => {
+        const child = spawn(process.execPath, [cliPath, ...args], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: process.env,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.stderr.on('data', (chunk) => (stderr += chunk.toString('utf8')));
+        const timer = setTimeout(() => child.kill(), WIRE_TIMEOUT_MS);
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            done({ code: 1, stdout, stderr: `${stderr}${error.message}` });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            done({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+export function firstRunWiring(options) {
+    const run = options.run ?? nodeRun(options.cliPath);
+    const done = new Map();
+    return {
+        projectDirectory: (cwd) => projectDirectoryOf(cwd),
+        wire(directory) {
+            const held = done.get(directory);
+            if (held !== undefined)
+                return held;
+            const outcome = run(['init', '--no-mcp', '--json', '--port', String(options.port)], directory)
+                .then(({ code, stdout, stderr }) => {
+                // Under --json the plan lines may go to stderr, keeping stdout for the one object.
+                const { result } = readInitOutput(stdout);
+                const { steps } = readInitOutput(`${stdout}\n${stderr}`);
+                const record = 'object' === typeof result && null !== result
+                    ? result
+                    : {};
+                const url = 'string' === typeof record['url'] ? record['url'] : undefined;
+                const ok = 0 === code && true === record['ok'];
+                const lastError = stderr.trim().split('\n').at(-1);
+                return {
+                    ok,
+                    directory,
+                    steps,
+                    ...(url === undefined ? {} : { url }),
+                    ...(ok
+                        ? {}
+                        : {
+                            error: lastError !== undefined && 0 < lastError.length
+                                ? lastError
+                                : `init exited ${String(code)}`,
+                        }),
+                };
+            })
+                .catch((error) => ({
+                ok: false,
+                directory,
+                steps: [],
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            done.set(directory, outcome);
+            return outcome;
+        },
+    };
+}

package/dist/portal/session/human/notes-ledger.d.ts

@@ -0,0 +1,20 @@
+import type { ReviewMark } from './review-store.js';
+/** One note as it lands on disk: the mark without its session-local id and clock. */
+type StoredNote = Omit<ReviewMark, 'id' | 'at'>;
+/** What `.reticle/notes.json` holds. Keyed by content, so a note survives the session it was made in. */
+export interface NotesFile {
+    notes: Record<string, StoredNote>;
+}
+/**
+ * Mark ids (`m1`, `m2`, …) restart with the daemon, so they cannot name a note across sessions.
+ * The route, anchor and words can: the same complaint on the same element is the same note.
+ */
+export declare function noteKey(mark: Pick<ReviewMark, 'route' | 'anchor' | 'note'>): string;
+/**
+ * Merge one session's marks into the project's notes file, so the HUD notes a human left reach the
+ * platform with the rest of `.reticle/` instead of dying with the session that held them.
+ *
+ * Never throws: a note that cannot be written must not break the event that carried it.
+ */
+export declare function recordNotes(reticleRoot: string | undefined, marks: readonly ReviewMark[]): void;
+export {};

package/dist/portal/session/human/notes-ledger.js

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+/** Enough for a project's review history; the oldest fall off first. */
+const MAX_NOTES = 500;
+/**
+ * Mark ids (`m1`, `m2`, …) restart with the daemon, so they cannot name a note across sessions.
+ * The route, anchor and words can: the same complaint on the same element is the same note.
+ */
+export function noteKey(mark) {
+    return createHash('sha256')
+        .update(`${mark.route ?? ''}\n${mark.anchor}\n${mark.note}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+function read(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return { notes: 'object' === typeof parsed.notes && null !== parsed.notes ? parsed.notes : {} };
+    }
+    catch {
+        return { notes: {} };
+    }
+}
+/**
+ * Merge one session's marks into the project's notes file, so the HUD notes a human left reach the
+ * platform with the rest of `.reticle/` instead of dying with the session that held them.
+ *
+ * Never throws: a note that cannot be written must not break the event that carried it.
+ */
+export function recordNotes(reticleRoot, marks) {
+    if (reticleRoot === undefined || 0 === marks.length)
+        return;
+    const path = join(reticleRoot, ReticleDir.NOTES_FILE);
+    try {
+        const held = read(path).notes;
+        for (const { id: _id, at: _at, ...note } of marks) {
+            const key = noteKey(note);
+            // Re-inserted so a note touched now counts as the newest when the oldest are dropped.
+            delete held[key];
+            held[key] = note;
+        }
+        const keys = Object.keys(held);
+        for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_NOTES)))
+            delete held[stale];
+        mkdirSync(reticleRoot, { recursive: true });
+        const tmp = `${path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify({ notes: held }, null, 2)}\n`, 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // Disk full or read-only checkout: the note is still in the session, just not on the platform.
+    }
+}

package/dist/portal/session/human/review-store.d.ts

@@ -30,8 +30,20 @@ interface ResolveOutcome {
     /** The retired mark's note. Absent when nothing was resolved. */
     note?: string;
 }
+/**
+ * Per-session store of human review marks (the "annotate the bug where you see it" inbox). A mark is
+ * added when a HUMAN_MARK event arrives, listed by the agent via reticle_review, and retired with
+ * resolve when the agent claims the fix — distinct from the live-control inbox, which is drained
+ * (delivered-once) on read. Marks persist (read does not consume) so the agent can list, fix, and
+ * THEN resolve, and a fix can be verified against the same mark.
+ *
+ * No IO of its own and no clock: `onChange` is how a caller keeps it on disk (see notes-ledger.ts).
+ * The id is a monotonic counter (m1, m2, …) so it is deterministic and never depends on
+ * Math.random/Date.now; the timestamp is passed in by the caller.
+ */
 export declare class ReviewStore {
     #private;
+    constructor(onChange?: (marks: ReviewMark[]) => void);
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
     add(data: HumanMarkData, at: number): ReviewMark;
     /** All marks still awaiting a fix, oldest first. Reading never consumes — resolve retires a mark. */

package/dist/portal/session/human/review-store.js

@@ -1,14 +1,4 @@
 import { MarkStatus } from '@reticlehq/core';
-/**
- * Per-session store of human review marks (the "annotate the bug where you see it" inbox). A mark is
- * added when a HUMAN_MARK event arrives, listed by the agent via reticle_review, and retired with
- * resolve when the agent claims the fix — distinct from the live-control inbox, which is drained
- * (delivered-once) on read. Marks persist (read does not consume) so the agent can list, fix, and
- * THEN resolve, and a fix can be verified against the same mark.
- *
- * Pure in-memory state: no IO, no clock. The id is a monotonic counter (m1, m2, …) so it is
- * deterministic and never depends on Math.random/Date.now; the timestamp is passed in by the caller.
- */
 /** Prefix on review-mark ids (m1, m2, …) — distinguishes them from command ids. */
 const MARK_ID_PREFIX = 'm';
 /**
@@ -29,8 +19,24 @@ let nextMarkId = 0;
 export function resetMarkIdsForTest() {
     nextMarkId = 0;
 }
+/**
+ * Per-session store of human review marks (the "annotate the bug where you see it" inbox). A mark is
+ * added when a HUMAN_MARK event arrives, listed by the agent via reticle_review, and retired with
+ * resolve when the agent claims the fix — distinct from the live-control inbox, which is drained
+ * (delivered-once) on read. Marks persist (read does not consume) so the agent can list, fix, and
+ * THEN resolve, and a fix can be verified against the same mark.
+ *
+ * No IO of its own and no clock: `onChange` is how a caller keeps it on disk (see notes-ledger.ts).
+ * The id is a monotonic counter (m1, m2, …) so it is deterministic and never depends on
+ * Math.random/Date.now; the timestamp is passed in by the caller.
+ */
 export class ReviewStore {
     #marks = [];
+    /** Told the full history after every add and resolve, so a caller can keep it on disk. */
+    #onChange;
+    constructor(onChange) {
+        this.#onChange = onChange;
+    }
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
     add(data, at) {
         nextMarkId += 1;
@@ -49,6 +55,7 @@ export class ReviewStore {
         if (data.route !== undefined)
             mark.route = data.route;
         this.#marks.push(mark);
+        this.#onChange?.(this.all());
         return mark;
     }
     /** All marks still awaiting a fix, oldest first. Reading never consumes — resolve retires a mark. */
@@ -84,6 +91,7 @@ export class ReviewStore {
         if (mark === undefined || mark.status === MarkStatus.RESOLVED)
             return { resolved: false, id };
         mark.status = MarkStatus.RESOLVED;
+        this.#onChange?.(this.all());
         return { resolved: true, id, note: mark.note };
     }
 }

package/dist/portal/session/live-control-tools.d.ts

@@ -1,15 +1,2 @@
 import type { ToolDef } from '../../surface/tools/tool-kit.js';
-/**
- * Live-control agent tools: the agent's side of the human-in-the-loop control surface.
- *
- * - reticle_end_session: terminal stop. Sets state `ended` and syncs the panel (PRESENTER) with an
- * optional summary. Idempotent — ending an already-ended session is a safe no-op.
- * - reticle_resume: clears a human pause. Sets state `active` and syncs the panel.
- * - reticle_messages: explicit poll — drains and returns the queued human notes.
- *
- * State changes go through `setState`, which echoes the state to the panel in a SINGLE PRESENTER
- * push (optionally carrying human-facing text, e.g. the end summary) — a transition never emits two
- * PRESENTER commands. No clock is read here — inbox stamps were assigned by the session's injected
- * elapsed clock at enqueue time.
- */
 export declare const LIVE_CONTROL_TOOLS: ToolDef[];

package/dist/portal/session/live-control-tools.js

@@ -34,18 +34,31 @@ function endingTurnWithNothingAttached(deps, id) {
  * PRESENTER commands. No clock is read here — inbox stamps were assigned by the session's injected
  * elapsed clock at enqueue time.
  */
+const DISCONNECT_NEEDS_SESSION_ID = '`disconnect: true` needs the `sessionId` of the page to detach — list them with ' +
+    'reticle_session{action:"list"}; it is never picked for you, because detaching the wrong window ' +
+    'cuts you off from the app.';
 export const LIVE_CONTROL_TOOLS = [
     {
         name: ReticleTool.END_SESSION,
         description: 'End this session for good — use ONLY when the whole task is complete. Sets state "ended" ' +
             '(calm, terminal) and shows the optional `summary` on the panel. If you are just finishing a ' +
-            'turn or waiting on the human, call reticle_session{action:"yield"} instead (revivable). Idempotent.',
-        inputSchema: { summary: z.string().optional(), ...sessionIdShape },
+            'turn or waiting on the human, call reticle_session{action:"yield"} instead (revivable). Idempotent. ' +
+            "With `disconnect: true` and a `sessionId` it also closes that page's connection and refuses it " +
+            'until the daemon restarts — for a stray window (a hidden desktop webview, a 404 page) that keeps coming back.',
+        inputSchema: {
+            summary: z.string().optional(),
+            disconnect: z
+                .boolean()
+                .optional()
+                .describe('Also detach this page for good (needs sessionId). Reloads stay detached.'),
+            ...sessionIdShape,
+        },
         // `sessionId` is optional because there may genuinely not be one — see the no-op below. An
         // empty string would read as a real id in a log, which is worse than its absence.
         outputSchema: {
             ended: z.boolean(),
             sessionId: z.string().optional(),
+            disconnected: z.boolean().optional(),
             note: z.string().optional(),
             talk_to_us: z
                 .string()
@@ -58,6 +71,10 @@ export const LIVE_CONTROL_TOOLS = [
         },
         handler: (deps, args) => {
             const requested = asString(args['sessionId']);
+            const detach = true === args['disconnect'];
+            // Named, never auto-picked: detaching the wrong window cuts the agent off from the app.
+            if (detach && requested === undefined)
+                throw new Error(DISCONNECT_NEEDS_SESSION_ID);
             if (endingTurnWithNothingAttached(deps, requested)) {
                 return Promise.resolve({ ended: true, note: YIELD_WITHOUT_SESSION_NOTE });
             }
@@ -97,7 +114,15 @@ export const LIVE_CONTROL_TOOLS = [
                 const panel = [summary, gap[0]].filter((line) => line !== undefined);
                 // One PRESENTER push for the transition; the summary and the gap headline ride together.
                 session.setState(SessionState.ENDED, 0 === panel.length ? undefined : panel.join('\n'));
-                return { ended: true, sessionId: session.id, gap, talk_to_us: DiscoveryInvite.AGENT };
+                if (detach)
+                    deps.sessions.park(session);
+                return {
+                    ended: true,
+                    sessionId: session.id,
+                    ...(detach ? { disconnected: true } : {}),
+                    gap,
+                    talk_to_us: DiscoveryInvite.AGENT,
+                };
             });
         },
     },

package/dist/portal/session/no-session-diagnosis.d.ts

@@ -166,6 +166,13 @@ export interface NoSessionFacts {
      * or the ring has forgotten — inventing a URL is worse than the silence this exists to end.
      */
     lastKnownUrl?: string;
+    /**
+     * Where the departed tab was seen heading, when the SDK reported a navigation just before the
+     * socket closed (#1256). Separate from `lastKnownUrl` — the old origin — because the 5xx probe
+     * and successor matching need the page the tab was ON, while the diagnosis needs where it was
+     * GOING. Absent unless the departure note arrived fresh.
+     */
+    departedTo?: string;
     /**
      * What a plain GET of `lastKnownUrl` answered, done out of band by the watch after the session
      * went. The one fact that separates a server error from a closed tab and from an install

package/dist/portal/session/no-session-diagnosis.js

@@ -12,6 +12,7 @@
  * the hot resolve() path and this stays unit-testable.
  */
 import { NoSessionReason } from '@reticlehq/core/telemetry';
+import { redactUrl } from '@reticlehq/core';
 import { leaseCaveat } from './presence/lease-availability.js';
 import { DEV_SERVER_PORTS } from '../../command/cli/ports/resolve/cli-port.js';
 import { siblingListenerNote } from '../../command/cli/ports/sibling-ports.js';
@@ -404,6 +405,20 @@ export function explainNoSession(facts) {
                 'the SDK cannot reconnect to it. Fix the route, then reload the tab' +
                 `${orOpenCommand(facts)}.${alreadyListeningClause(listening)} ${RETRY}`);
         }
+        // Ranked above TAB_GONE because it is not a hedge: the SDK reported the departure while the
+        // old document was still alive, so this is where the tab WENT rather than one of several
+        // opposite situations. Ranked below ROUTE_SERVER_ERROR because that branch names a defect in
+        // the app itself. Only reached when the departure note arrived fresh — a stale note is no
+        // fact, and the tombstone already refused to carry one (#1256).
+        if (facts.departedTo !== undefined && '' !== facts.departedTo) {
+            return reason(NoSessionReason.NAVIGATED_AWAY, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
+                // Redacted: a redirect target can carry credentials (OAuth callbacks, reset links), and
+                // this message is agent-facing. The raw value stays on the tombstone for matching.
+                `is correct. The page navigated away to ${redactUrl(facts.departedTo)} just before the ` +
+                'connection closed — that is where the tab went, not a closed tab and not an install ' +
+                `problem. Ask the human to go back to the app${orOpenCommand(facts)}, or reload the tab. ` +
+                `${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());
+        }
         return reason(NoSessionReason.TAB_GONE, 'no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             `is correct. ${tabGoneWhat(facts.lastKnownUrl)} Ask the human to reopen ` +
             `the app${orOpenCommand(facts)}, or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`, alreadyListeningClause(listening).trim());

package/dist/portal/session/no-session-next-action.d.ts

@@ -29,6 +29,11 @@ interface NextActionFacts {
     initialized: boolean;
     listening: readonly number[];
     dev: DevCommand | undefined;
+    /**
+     * File-existence predicate for the project root, pure for testing.
+     * Used to recognize non-JS ecosystems (e.g. Flutter) when no dev script exists.
+     */
+    exists?: (file: string) => boolean;
     /** Configs found in other workspace directories: positive evidence of a scope mismatch. */
     configsElsewhere?: readonly {
         directory: string;
@@ -82,6 +87,12 @@ interface NextActionFacts {
      * its one hit is as likely to be another repo's dev server as this one's.
      */
     lastKnownUrl?: string;
+    /**
+     * Where the departed tab was seen heading, when the SDK reported it fresh (#1256). The
+     * next-action reason must agree with the diagnosis: when this is present the tab was not
+     * closed, it navigated away.
+     */
+    departedTo?: string;
 }
 export declare function nextActionFor(facts: NextActionFacts): NoSessionNextAction;
 /** The same action as one sentence, for the prose message the human reads. */

package/dist/portal/session/no-session-next-action.js

@@ -12,7 +12,8 @@
  *
  * Pure. The facts arrive from the watch; nothing here touches the disk or the clock.
  */
-import { NoSessionAction, RETICLE_URL_PARAM, ReticleEnv } from '@reticlehq/core';
+import { NoSessionAction, RETICLE_URL_PARAM, ReticleEnv, redactUrl } from '@reticlehq/core';
+import { detectNonJsEcosystem, noPackageJsonMessage } from '@reticlehq/init';
 /**
  * The departed session's url as a human would type it: the params a Reticle launcher stamps on a
  * lease are stripped, because reopening WITH them would adopt the dead lease's identity. Undefined
@@ -88,12 +89,19 @@ export function nextActionFor(facts) {
             : only === undefined
                 ? {}
                 : { command: `${OPEN_COMMAND} ${LOCALHOST}:${String(only)}`, port: only };
+        // Where the tab was seen heading, when the SDK reported it fresh — the next action must
+        // tell the same story as the diagnosis (#1256).
+        const departedTo = facts.departedTo;
         return {
             action: NoSessionAction.REOPEN_APP,
             ...target,
-            reason: 'a session was connected to this daemon earlier, so the wiring is correct — the tab was ' +
-                'closed, reloaded, or the lease aged out. Reopen the app, or take one you own with ' +
-                'reticle_lease {action:"acquire", url}.' +
+            reason: 'a session was connected to this daemon earlier, so the wiring is correct — ' +
+                // Agrees with the diagnosis: when the SDK saw the page leave, "the tab was closed" is
+                // the wrong story. Redacted like the diagnosis — this reason is agent-facing too.
+                (departedTo === undefined || '' === departedTo
+                    ? 'the tab was closed, reloaded, or the lease aged out. '
+                    : `the page navigated away to ${redactUrl(departedTo)}. `) +
+                'Reopen the app, or take one you own with reticle_lease {action:"acquire", url}.' +
                 bound,
         };
     }
@@ -119,6 +127,20 @@ export function nextActionFor(facts) {
     if (0 === facts.listening.length) {
         const dev = facts.dev;
         if (dev === undefined) {
+            if (facts.exists !== undefined && !facts.exists('package.json')) {
+                const ecosystem = detectNonJsEcosystem(facts.exists);
+                if (ecosystem !== undefined) {
+                    return {
+                        action: NoSessionAction.START_DEV_SERVER,
+                        reason: 'Flutter' === ecosystem
+                            ? noPackageJsonMessage(facts.exists)
+                            : `This looks like a ${ecosystem} project, with no package.json in this directory. ` +
+                                'There is no dev command to hand you. Ask the human how the app starts and which ' +
+                                'URL it serves. If the web app has its own package.json in another directory, ' +
+                                'run Reticle from that app directory instead.',
+                    };
+                }
+            }
             return {
                 action: NoSessionAction.START_DEV_SERVER,
                 reason: 'nothing is listening on the ports Reticle scans, so the app is probably not running — ' +
@@ -127,9 +149,12 @@ export function nextActionFor(facts) {
                     'started, and for the URL it serves on.',
             };
         }
+        // The app can live one directory down; the command has to be runnable from where the daemon
+        // stands, so it carries its own `cd` (reticle#1368).
+        const inApp = dev.directory === undefined ? '' : `cd ${dev.directory} && `;
         return {
             action: NoSessionAction.START_DEV_SERVER,
-            command: dev.command,
+            command: `${inApp}${dev.command}`,
             ...(dev.port === undefined ? {} : { port: dev.port }),
             // "Probably", to match the branch above it and the paragraph beside it.
             //
@@ -147,6 +172,7 @@ export function nextActionFor(facts) {
                 'though that scan is narrow, so if it IS up on another port, ask for its URL instead of ' +
                 `starting a second one. This is the project's own ` +
                 (undefined === dev.script ? 'launcher' : `\`${dev.script}\` script`) +
+                (dev.directory === undefined ? '' : `, in \`${dev.directory}\``) +
                 ` — run it in the ` +
                 'background, tell the human it is running, then call reticle_sessions again.',
         };

package/dist/portal/session/no-session-watch.d.ts

@@ -17,7 +17,20 @@ interface NoSessionWatchOptions {
     initialized: boolean;
     /** Where that was decided — this daemon's working directory unless a caller says otherwise. */
     directory?: string;
-    probe?: () => Promise<number[]>;
+    /**
+     * File-existence predicate for the project directory. Injected for tests; defaults to
+     * checking the directory on disk.
+     */
+    exists?: (file: string) => boolean;
+    /**
+     * The background port scan. Injected for tests; production probes each port on both loopback
+     * families.
+     *
+     * Receives the candidate list — the well-known ports plus the ones that name THIS project
+     * (#1367) — so a test can pin the observation without opening a socket. A test that injects it
+     * owns the scan.
+     */
+    probe?: (ports: readonly number[]) => Promise<number[]>;
     /**
      * Well-known Reticle ports other than ours that currently accept a connection.
      *