@onepointfour-packs/flaredeck-agent 0.1.0 → 0.2.0

package/dist/engine.d.ts

@@ -70,9 +70,37 @@ export type RunContext = {
         runs?: ToolSet;
         schedules?: ToolSet;
         flaredeck?: ToolSet;
+        /** A real browser, when this card has an environment to point it at. */
+        browser?: ToolSet;
     };
     /** Hooks the harness insists on, whatever the engine: the guards. */
     guard?: unknown;
+    /**
+     * Publish this card's branch. An out-of-process engine cannot reach the in-process publishing
+     * tool, which left a Gemini agent with no way to publish at all — and reporting that it had.
+     */
+    publish?: () => Promise<{
+        ok: boolean;
+        text: string;
+    }>;
+    /** Why this card may not be called finished yet, or null when it may. */
+    finish?: () => Promise<string | null>;
+    /** The card a tool call names, so the pane can say what is being worked, not what woke it. */
+    noteCard?: (code: string) => void;
+    /** Which FlareDeck tools this agent is offered. Absent means all of them. */
+    keep?: (name: string) => boolean;
+    /**
+     * Who this agent is and how it works — the standing brief, as opposed to this turn's. The
+     * Claude engine appends it to its system prompt; an out-of-process engine needs it passed.
+     */
+    standing?: string;
+    /** What is in this card's branch, appended to anything the agent says. */
+    saved?: () => Promise<{
+        branch: string;
+        commits: number;
+        pushed: boolean;
+        known?: boolean;
+    } | null>;
 };
 export type ToolSet = {
     server: unknown;

package/dist/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAsGA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAA6C;IAC3E,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACjG,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QAC5D,OAAO,IAAI,YAAY,EAAE,CAAC;IAC5B,CAAC;IACD,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QAC5B,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACtE,OAAO,IAAI,iBAAiB,EAAE,CAAC;IACjC,CAAC;IACD,6FAA6F;IAC7F,4EAA4E;IAC5E,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,oCAAoC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;CAAG"}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AA0HA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAA6C;IAC3E,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACjG,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QAC5D,OAAO,IAAI,YAAY,EAAE,CAAC;IAC5B,CAAC;IACD,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QAC5B,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACtE,OAAO,IAAI,iBAAiB,EAAE,CAAC;IACjC,CAAC;IACD,6FAA6F;IAC7F,4EAA4E;IAC5E,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,oCAAoC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;CAAG"}

package/dist/env.d.ts

@@ -1 +1,5 @@
-export {};
+/**
+ * The environment to give a child process: ours, minus the NODE_ENV we invented for Ink. An
+ * explicit NODE_ENV from the person's own shell is theirs and is passed through untouched.
+ */
+export declare function childEnv(extra?: Record<string, string>): NodeJS.ProcessEnv;

package/dist/env.js

@@ -5,6 +5,24 @@
 // them, so a daemon that repaints a status line all day accumulates a million entries
 // ("MaxPerformanceEntryBufferExceededWarning") and grows without bound. Nothing else in the
 // harness reads NODE_ENV, so defaulting it costs nothing and an explicit value still wins.
+//
+// It is NOT free for the agent, though, and that took a while to notice. Every child process
+// inherits it, so `npm ci` in a fresh worktree skipped devDependencies and left no tsc, no tsx
+// and no drizzle-kit — on cards whose own instructions say to typecheck. An agent wrote the
+// workaround into its notes as if it were a property of the project: "shell has
+// NODE_ENV=production ... must run npm ci --include=dev".
+//
+// So the value is remembered, and `childEnv()` hands children the environment as it was.
+const INHERITED = process.env['NODE_ENV'];
 process.env['NODE_ENV'] ??= 'production';
-export {};
+/**
+ * The environment to give a child process: ours, minus the NODE_ENV we invented for Ink. An
+ * explicit NODE_ENV from the person's own shell is theirs and is passed through untouched.
+ */
+export function childEnv(extra = {}) {
+    const env = { ...process.env, ...extra };
+    if (INHERITED === undefined)
+        delete env['NODE_ENV'];
+    return env;
+}
 //# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,EAAE;AACF,4FAA4F;AAC5F,yFAAyF;AACzF,sFAAsF;AACtF,4FAA4F;AAC5F,2FAA2F;AAC3F,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,EAAE;AACF,4FAA4F;AAC5F,yFAAyF;AACzF,sFAAsF;AACtF,4FAA4F;AAC5F,2FAA2F;AAC3F,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,4FAA4F;AAC5F,gFAAgF;AAChF,0DAA0D;AAC1D,EAAE;AACF,yFAAyF;AACzF,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC1C,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,QAAgC,EAAE;IACzD,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IACzC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC;IACpD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/environment.d.ts

@@ -15,15 +15,59 @@
  * says, and the agent is told.
  */
 export declare const START_SCRIPT: string;
+/**
+ * What a project may tell the harness about its own environment.
+ *
+ * The old contract was `name=url` lines, which says where things are and nothing else — so an
+ * agent that got the app running still had to work out how to log into it, how to get data into
+ * it, and whether any of that was safe. It guessed, or it asked, or it stopped.
+ *
+ * A project that wants more says so in JSON, printed on one line or fenced between
+ * FLAREDECK_ENV_START and FLAREDECK_ENV_END. Everything in it is optional; a project that only
+ * prints `api=http://localhost:3000` keeps working exactly as before.
+ */
+export type EnvContract = {
+    /** Where things ended up. The old `name=url` lines land here too. */
+    parts?: Record<string, string>;
+    /** How to get in. Test credentials for a local environment, never production ones. */
+    credentials?: Record<string, {
+        username?: string;
+        password?: string;
+        note?: string;
+    } | string>;
+    /** Things an agent may run, and what each one does. */
+    scripts?: Record<string, {
+        path?: string;
+        does?: string;
+    } | string>;
+    /** Anything else the next agent needs: "run seed before testing onboarding". */
+    notes?: string;
+};
 export type Started = {
     ran: boolean;
     ok: boolean;
     /** Whatever the script announced: api, ui, db… */
     endpoints: Record<string, string>;
     detail: string;
+    /** The structured contract, when the project printed one. */
+    contract?: EnvContract;
 };
-export declare function hasStartScript(repo: string): boolean;
-export declare function startEnvironment(repo: string, onStep: (text: string) => void): Promise<Started>;
+/**
+ * Which script brings this project up, and where it is.
+ *
+ * The path is relative to the REPOSITORY root, which is the only arrangement that works: it is
+ * committed, so it is present in every worktree automatically, and it runs with the worktree as
+ * its working directory — against this card's code rather than whatever the shared checkout is
+ * sitting on. A board declaring `tools/dev.sh` means `<worktree>/tools/dev.sh`.
+ */
+export declare function startScriptPath(repo: string, declared?: string): string | null;
+export declare function hasStartScript(repo: string, declared?: string): boolean;
+export declare function startEnvironment(repo: string, onStep: (text: string) => void, declared?: string): Promise<Started>;
+/**
+ * The JSON contract, if the script printed one. Fenced output is read first because a script that
+ * logs freely cannot be trusted to keep its JSON on one tidy line.
+ */
+export declare function readContract(out: string): EnvContract | undefined;
 /** What the agent is told about where things are, or why it cannot start. */
 /**
  * `needsRunning` is Jev's answer to whether this card can be done without the project running —
@@ -37,3 +81,44 @@ export declare function startEnvironment(repo: string, onStep: (text: string) =>
  * about it.
  */
 export declare function environmentBrief(started: Started, repo: string, needsRunning?: boolean): string;
+/**
+ * Told to an agent whose card did not look like it needed the project running.
+ *
+ * Starting it is minutes — an install, a database, servers — and most cards never touch a running
+ * thing: a stylesheet nudge, a copy change, a guard clause. The judgement can be wrong, so this
+ * says plainly that it was a judgement and how to overturn it, rather than leaving the agent to
+ * conclude the project cannot be run here.
+ */
+export declare function notStartedBrief(skipped: boolean, repo: string): string;
+/**
+ * The rest of what the project said about its environment: how to log in, what may be run, and
+ * whatever the last person wished they had been told.
+ *
+ * Addresses alone leave an agent with a running app it cannot get into. Everything here is
+ * optional, and a project that says nothing produces nothing.
+ */
+export declare function contractBrief(c: EnvContract | undefined): string;
+/**
+ * Whether the environment this card is testing is actually this card's.
+ *
+ * Several worktrees run side by side, and a front end built against a hardcoded port will, in
+ * the second one, reach the FIRST worktree's API. Nothing errors — it answers perfectly, running
+ * somebody else's code, so the agent tests a change that is not there or cannot reproduce a bug
+ * that is. Guidance alone does not catch a script that gets this wrong; this does.
+ *
+ * For each address the script printed, find the process listening on that port and ask which
+ * directory it is running from. A listener whose working directory is a DIFFERENT worktree is
+ * conclusive: that part belongs to another card.
+ *
+ * Deliberately quiet about everything else. A process started from the repository root, a docker
+ * container, anything it cannot resolve — none of those are evidence of a problem, and a check
+ * that cries wolf gets ignored exactly when it matters.
+ */
+export declare function crossWired(endpoints: Record<string, string>, worktree: string): Promise<string[]>;
+/**
+ * What to say about the browser, which is only worth saying when there is something to look at.
+ *
+ * An agent with a running environment and no way to see it writes "verified by reading the code",
+ * which is not verification. An agent that HAS a browser and is not told so writes the same thing.
+ */
+export declare function browserBrief(hasBrowser: boolean, endpoints: Record<string, string>): string;

package/dist/environment.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 /**
  * Get the project running, if it has told us how.
@@ -19,14 +19,35 @@ import { join } from 'node:path';
  */
 export const START_SCRIPT = join('.flaredeck', 'start.sh');
 const TIMEOUT_MS = 5 * 60 * 1000;
-export function hasStartScript(repo) {
-    return existsSync(join(repo, START_SCRIPT));
+/**
+ * Which script brings this project up, and where it is.
+ *
+ * The path is relative to the REPOSITORY root, which is the only arrangement that works: it is
+ * committed, so it is present in every worktree automatically, and it runs with the worktree as
+ * its working directory — against this card's code rather than whatever the shared checkout is
+ * sitting on. A board declaring `tools/dev.sh` means `<worktree>/tools/dev.sh`.
+ */
+export function startScriptPath(repo, declared) {
+    const wanted = (declared ?? '').trim().replace(/^\.\//, '');
+    // A declared path that is not there is worth saying out loud rather than silently falling back
+    // to a default the board did not ask for.
+    if (wanted)
+        return existsSync(join(repo, wanted)) ? wanted : null;
+    return existsSync(join(repo, START_SCRIPT)) ? START_SCRIPT : null;
 }
-export async function startEnvironment(repo, onStep) {
-    if (!hasStartScript(repo))
+export function hasStartScript(repo, declared) {
+    return startScriptPath(repo, declared) !== null;
+}
+export async function startEnvironment(repo, onStep, declared) {
+    const script = startScriptPath(repo, declared);
+    if (!script) {
+        if ((declared ?? '').trim()) {
+            onStep(`this board declares ${declared} as its start script, and it is not in the checkout`);
+        }
         return { ran: false, ok: true, endpoints: {}, detail: '' };
-    onStep('starting the environment');
-    const { code, out } = await run(`bash ${START_SCRIPT}`, repo);
+    }
+    onStep(`starting the environment (${script})`);
+    const { code, out } = await run(`bash ${script}`, repo);
     const endpoints = {};
     for (const line of out.split('\n')) {
         // `name=value`, one per line, value running to the end. Tolerant of surrounding noise, since
@@ -36,6 +57,10 @@ export async function startEnvironment(repo, onStep) {
         if (m?.[1] && m[2])
             endpoints[m[1]] = m[2];
     }
+    const contract = readContract(out);
+    // A contract's own parts are the authority; the loose lines fill anything it did not name.
+    for (const [k, v] of Object.entries(contract?.parts ?? {}))
+        endpoints[k] = v;
     const names = Object.keys(endpoints);
     onStep(code === 0
         ? `environment ready${names.length ? ` — ${names.join(', ')}` : ''}`
@@ -45,8 +70,29 @@ export async function startEnvironment(repo, onStep) {
         ok: code === 0,
         endpoints,
         detail: out.trim().split('\n').slice(-5).join('\n').slice(0, 600),
+        ...(contract ? { contract } : {}),
     };
 }
+/**
+ * The JSON contract, if the script printed one. Fenced output is read first because a script that
+ * logs freely cannot be trusted to keep its JSON on one tidy line.
+ */
+export function readContract(out) {
+    const fenced = /FLAREDECK_ENV_START\s*([\s\S]*?)\s*FLAREDECK_ENV_END/.exec(out);
+    const candidates = fenced?.[1]
+        ? [fenced[1]]
+        : out.split('\n').filter((l) => l.trim().startsWith('{') && l.trim().endsWith('}'));
+    for (const text of candidates.reverse()) {
+        try {
+            const doc = JSON.parse(text);
+            if (doc && typeof doc === 'object' && (doc.parts || doc.credentials || doc.scripts || doc.notes)) {
+                return doc;
+            }
+        }
+        catch { /* not this line */ }
+    }
+    return undefined;
+}
 /** What the agent is told about where things are, or why it cannot start. */
 /**
  * `needsRunning` is Jev's answer to whether this card can be done without the project running —
@@ -75,14 +121,18 @@ export function environmentBrief(started, repo, needsRunning = false) {
     }
     if (!started.ok) {
         return (`\n\nSTOP — ${START_SCRIPT} failed, so the environment is not up:\n${started.detail}\n\n` +
-            `Do not diagnose the code: nothing is running, so anything you conclude would be wrong. If ` +
-            `the fix is obviously in the start script itself, fix that. Otherwise say on the card what ` +
-            `failed, call set-needs-human, and stop.`);
+            `This is not your card's problem to solve. A board that issues cards needing the project ` +
+            `running owes its agents a start script that works in a fresh worktree, and keeping it ` +
+            `working is the lead's job, not yours. Do not diagnose the code — nothing is running, so ` +
+            `anything you conclude would be wrong — and do not start rebuilding the environment by ` +
+            `hand. Tell your lead what failed, with the output above, say the same on the card, and ` +
+            `stop. If the fix is obviously IN the start script and small, you may fix that one file.`);
     }
     const listed = Object.entries(started.endpoints).map(([k, v]) => `  · ${k}: ${v}`).join('\n');
-    return listed
+    const head = listed
         ? `\n\nThe environment is up and these are its addresses — use them rather than assuming ports:\n${listed}`
         : `\n\nThe environment started cleanly (${repo}/${START_SCRIPT}).`;
+    return head + contractBrief(started.contract);
 }
 function run(command, cwd) {
     return new Promise((resolve) => {
@@ -97,4 +147,156 @@ function run(command, cwd) {
         child.on('error', (e) => { clearTimeout(timer); resolve({ code: 1, out: String(e) }); });
     });
 }
+/**
+ * Told to an agent whose card did not look like it needed the project running.
+ *
+ * Starting it is minutes — an install, a database, servers — and most cards never touch a running
+ * thing: a stylesheet nudge, a copy change, a guard clause. The judgement can be wrong, so this
+ * says plainly that it was a judgement and how to overturn it, rather than leaving the agent to
+ * conclude the project cannot be run here.
+ */
+export function notStartedBrief(skipped, repo) {
+    if (!skipped)
+        return '';
+    return (`\n\nThe project is NOT running. This card did not look like one that needs it, so nothing ` +
+        `was started and you have your checkout and the code. Do not start it out of habit: for a ` +
+        `small change, reading the code and the project's own checks (a typecheck, a lint, a verify ` +
+        `script) is both faster and better evidence than a screenshot.\n\n` +
+        `If you DO need it — you are changing behaviour rather than appearance, or you want to see ` +
+        `it in a browser — start it DETACHED, never in the foreground:\n\n` +
+        `    ( bash ${START_SCRIPT} > /tmp/env.log 2>&1 & ) ; sleep 25 ; tail -40 /tmp/env.log\n\n` +
+        `${START_SCRIPT} brings up servers and does not return, so running it and waiting is a turn ` +
+        `that never ends — the harness runs it with a timeout for exactly that reason, and your ` +
+        `shell has none. Read the \`name=url\` lines it prints for where things ended up, and poll ` +
+        `the log again if it is not ready yet.\n\n` +
+        `**A check that fails because something is not RUNNING or not MIGRATED is a reason to start ` +
+        `the environment, not a reason to report that you could not run it.** A missing table or ` +
+        `column, a refused connection, an empty database — the start script makes a fresh one of its ` +
+        `own, already migrated. Start it, run the check again, and report what it then said. Only say ` +
+        `a check could not be run once you have tried it with the environment up.`);
+}
+/**
+ * The rest of what the project said about its environment: how to log in, what may be run, and
+ * whatever the last person wished they had been told.
+ *
+ * Addresses alone leave an agent with a running app it cannot get into. Everything here is
+ * optional, and a project that says nothing produces nothing.
+ */
+export function contractBrief(c) {
+    if (!c)
+        return '';
+    const out = [];
+    const creds = Object.entries(c.credentials ?? {});
+    if (creds.length) {
+        out.push('\nHow to sign in (these are this environment\'s own test accounts):');
+        for (const [who, v] of creds) {
+            if (typeof v === 'string') {
+                out.push(`  · ${who}: ${v}`);
+                continue;
+            }
+            const bits = [v.username && `username ${v.username}`, v.password && `password ${v.password}`, v.note]
+                .filter(Boolean).join(' · ');
+            out.push(`  · ${who}: ${bits}`);
+        }
+    }
+    const scripts = Object.entries(c.scripts ?? {});
+    if (scripts.length) {
+        out.push('\nScripts this project says you may run:');
+        for (const [name, v] of scripts) {
+            if (typeof v === 'string') {
+                out.push(`  · ${name}: ${v}`);
+                continue;
+            }
+            out.push(`  · ${name}${v.path ? ` (${v.path})` : ''}${v.does ? ` — ${v.does}` : ''}`);
+        }
+    }
+    if (c.notes?.trim())
+        out.push(`\nFrom the project: ${c.notes.trim()}`);
+    return out.length ? `\n${out.join('\n')}` : '';
+}
+/**
+ * Whether the environment this card is testing is actually this card's.
+ *
+ * Several worktrees run side by side, and a front end built against a hardcoded port will, in
+ * the second one, reach the FIRST worktree's API. Nothing errors — it answers perfectly, running
+ * somebody else's code, so the agent tests a change that is not there or cannot reproduce a bug
+ * that is. Guidance alone does not catch a script that gets this wrong; this does.
+ *
+ * For each address the script printed, find the process listening on that port and ask which
+ * directory it is running from. A listener whose working directory is a DIFFERENT worktree is
+ * conclusive: that part belongs to another card.
+ *
+ * Deliberately quiet about everything else. A process started from the repository root, a docker
+ * container, anything it cannot resolve — none of those are evidence of a problem, and a check
+ * that cries wolf gets ignored exactly when it matters.
+ */
+export async function crossWired(endpoints, worktree) {
+    // Resolved, both sides. macOS reports /private/var/... where the harness holds /var/..., and a
+    // path comparison that misses that accuses an agent of testing someone else's code when it is
+    // testing its own — which is how a check earns a reputation for crying wolf and gets ignored.
+    const mine = realpathSafe(worktree);
+    const found = [];
+    for (const [name, value] of Object.entries(endpoints)) {
+        const port = /(?::|\blocalhost:|\b127\.0\.0\.1:)(\d{2,5})\b/.exec(String(value))?.[1];
+        if (!port)
+            continue;
+        const owner = await listenerCwd(port);
+        if (!owner)
+            continue;
+        // Only a sibling worktree is proof. Anything else is a legitimate way to run a service.
+        const sibling = /\/\.worktrees-[^/]+\/[^/]+/.exec(owner)?.[0];
+        if (!sibling)
+            continue;
+        if (owner === mine || owner.startsWith(`${mine}/`))
+            continue;
+        found.push(`${name} (${value}) is served by a process running in ${owner} — that is ANOTHER card's ` +
+            `checkout, not yours (${mine}). You would be testing its code and believing the result.`);
+    }
+    return found;
+}
+/** Both sides of every path comparison go through this. See the note in crossWired. */
+function realpathSafe(path) {
+    try {
+        return realpathSync(path).replace(/\/+$/, '');
+    }
+    catch {
+        return path.replace(/\/+$/, '');
+    }
+}
+/** The working directory of whatever is listening on a port, or null. */
+async function listenerCwd(port) {
+    const { execFile } = await import('node:child_process');
+    const run = (cmd, args) => new Promise((resolve) => {
+        execFile(cmd, args, { timeout: 5000 }, (err, out) => resolve(err ? '' : String(out)));
+    });
+    const pids = (await run('lsof', ['-nP', '-t', `-i:${port}`, '-sTCP:LISTEN'])).trim().split('\n').filter(Boolean);
+    for (const pid of pids.slice(0, 3)) {
+        const cwd = (await run('lsof', ['-a', '-p', pid, '-d', 'cwd', '-Fn']))
+            .split('\n').find((l) => l.startsWith('n'))?.slice(1).trim();
+        if (cwd)
+            return realpathSafe(cwd);
+    }
+    return null;
+}
+/**
+ * What to say about the browser, which is only worth saying when there is something to look at.
+ *
+ * An agent with a running environment and no way to see it writes "verified by reading the code",
+ * which is not verification. An agent that HAS a browser and is not told so writes the same thing.
+ */
+export function browserBrief(hasBrowser, endpoints) {
+    if (!hasBrowser)
+        return '';
+    const part = endpoints['ui'] ? 'ui' : Object.keys(endpoints)[0] ?? 'ui';
+    return (`\n\nYou can look at this with a real browser. \`open_page\` takes the NAME of a part — ` +
+        `\`${part}\` — not a port, because every worktree runs on different ones. It gives you the page ` +
+        `as a list of what is on it, by role and name; click and fill take those same names, so you ` +
+        `never write a selector.\n\n` +
+        `Use it when a card is about something a person SEES — layout, wording, whether a control ` +
+        `works. For anything else the project's own checks are faster and better evidence. If the ` +
+        `card asks for a picture, \`screenshot\` saves one in your checkout to attach.\n\n` +
+        `When you work something out that the next session would have to work out again — how to ` +
+        `sign in, where a screen lives — \`remember\` it. That is kept against the project rather ` +
+        `than this card, so it is still there on the next one, and signing in is saved with it.`);
+}
 //# sourceMappingURL=environment.js.map

package/dist/environment.js.map

@@ -1 +1 @@
-{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"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"}

package/dist/flaredeck-proxy.d.ts

@@ -52,8 +52,54 @@ export declare function discoverFlaredeck(mcpUrl: string, token: string): Promis
  * works; only the argument check is looser.
  */
 export declare function zodFor(schema: JsonSchema | undefined, notes: string[], path?: string): ZodTypeAny;
+/**
+ * What this agent has actually saved, appended to anything it SAYS.
+ *
+ * The finish gate guards the board: it refuses a card being moved or marked done on an empty
+ * branch. It cannot see prose. HAL told its lead a fix was "fully completed" in a message, never
+ * touched a status tool, and the gate was never consulted — the card sat in Doing with a branch
+ * holding nothing but lockfile churn from an install.
+ *
+ * So every comment and message from an agent working a card carries one line of ground truth.
+ * Not a judgement about what it wrote, which would need to guess at meaning and would guess
+ * wrong: just what is in the branch, every time, so a claim and its evidence arrive together.
+ */
+export declare function workFooter(state: {
+    branch: string;
+    commits: number;
+    pushed: boolean;
+    known?: boolean;
+} | null): string;
+/**
+ * Tools a worker is not given.
+ *
+ * Every tool costs its description and schema in the prompt on EVERY turn — about 3,200
+ * characters of description alone across the full set, before schemas — and a longer menu is also
+ * a worse menu: more ways to pick the wrong thing. None of these belong to an agent whose job is
+ * cards and code.
+ *
+ * A lead keeps the lot: the portfolio and conversation tools are its surface, not noise.
+ */
+export declare const NOT_FOR_WORKERS: readonly string[];
+export declare function cardIn(args: Record<string, unknown>): string;
+export declare function CLAIMS_DONE(name: string, args: Record<string, unknown>): boolean;
 /** The in-process server: FlareDeck's tools, forwarded with a fresh token each time. */
-export declare function flaredeckProxy(serverName: string, mcpUrl: string, token: () => Promise<string>, discovered: Discovered, warn?: (s: string) => void): {
+export declare function flaredeckProxy(serverName: string, mcpUrl: string, token: () => Promise<string>, discovered: Discovered, warn?: (s: string) => void, 
+/**
+ * Why this card may not be called finished yet, or null when it may. Consulted at the moment a
+ * tool would report it done, because that is the only moment a wrong claim can still be caught.
+ */
+tooEarly?: () => Promise<string | null>, 
+/** The card a call names, so the pane can say what is being worked rather than what woke it. */
+onCard?: (code: string) => void, 
+/** Which tools this agent gets. Everything, for a lead. */
+keep?: (name: string) => boolean, 
+/** What is in this card's branch right now, for the footer on anything it says. */
+saved?: () => Promise<{
+    branch: string;
+    commits: number;
+    pushed: boolean;
+} | null>): {
     server: unknown;
     toolNames: string[];
 };