looply-cli 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vuedale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# looply
+
+**looply does not write your code.** Your coding agent does — Claude Code, or whichever
+one you already use. looply is the harness around it: it decides what the agent works
+on, refuses the paths you named, runs your checks, has a *second* agent prove the change
+against the task, and then keeps it or throws it away.
+
+Your code never leaves your machine.
+
+```sh
+npx looply-cli init      # read the repo, ask the few things it cannot infer
+npx looply-cli doctor    # run every check once — no agent calls, no cost
+npx looply-cli scan      # fill the queue with findings tied to a file and a line
+npx looply-cli verify    # confirm each finding against the code as it stands
+npx looply-cli run --hours 4
+```
+
+## The two-key rule
+
+A round commits only if **both** keys turn:
+
+| | |
+|---|---|
+| **Key one** | your own checks — typecheck, tests, build — in the order you wrote them |
+| **Key two** | a second agent reads the diff against the task. It did not write the code, and it never sees the first agent's account of what it did. |
+
+Either one fails and the work is discarded, the tree is cleaned, and the task goes back
+in the queue carrying the reason — so the next attempt starts knowing what went wrong
+with the last one.
+
+This exists because of a measured failure. An earlier version of this harness ran 166
+unattended rounds and kept all 166, because the checks it ran were the same checks the
+agent had already run before finishing. A green build is not evidence. **A prover that
+never rejects anything is not checking.**
+
+## What one round is
+
+```
+pick → implement → check → prove → keep or discard
+```
+
+- **pick** — the top item whose premise still holds. If the code moved under it, it goes
+  back through verification first: an item describing a bug somebody already fixed is
+  worse than no item at all.
+- **implement** — your agent, starting at the file and line the item already located.
+- **check** — your gates, cheapest first, stopping at the first failure.
+- **prove** — the second agent.
+- **keep or discard** — a commit on the run branch with a trailer naming only the checks
+  that actually ran, or nothing at all.
+
+## Rails
+
+Name the paths the agent must never touch. looply reports what it finds there and
+refuses the edit; a task that genuinely needs one becomes a question, for that one file,
+once.
+
+```yaml
+rails:
+  forbidden_paths: ["prisma/", "src/auth/", "src/modules/payments/"]
+  prod_patterns: [herokuapp, amazonaws, ".render.com"]
+  exemptions: ask     # or never
+```
+
+A railed path or a reachable production database **aborts** the round before a single
+check runs. That is a different thing from a failing check, and it is reported
+differently.
+
+## Commands
+
+| command | what it is for | costs |
+|---|---|---|
+| `looply` | where you are, and the single most useful next step | — |
+| `looply init` | profile the project and write `.looply/config.yaml` | — |
+| `looply doctor` | validate the config and run every check once | — |
+| `looply scan` | read the code through several lenses and fill the queue | agent |
+| `looply verify` | confirm draft items against the code, so a run can pick them | agent |
+| `looply run --hours N` | work the queue for N hours | agent |
+| `looply run --dry-run` | print exactly what a run would do | — |
+| `looply status` | what it is doing right now | — |
+| `looply report` | what a finished run actually did | — |
+| `looply pair` | connect this machine to your phone | — |
+| `looply daemon` | stay connected so the phone can drive it | — |
+| `looply agent --json` | machine-readable state, for other tools | — |
+
+`doctor` and `--dry-run` cost nothing. Use them rather than starting a run to find out
+the config is wrong.
+
+## Using a different agent
+
+The prompt is written to the agent's **stdin**, never onto a command line, so a
+multi-line prompt and a diff full of quotes are not your problem:
+
+```yaml
+agent:
+  command: "claude -p --dangerously-skip-permissions"
+  output_format_flag: "--output-format"   # "" if your agent has no such flag
+```
+
+The agent runs **contained**: it inherits no PATH and no environment, which is
+the point — but it means a provider outside your project has to be named, or it
+cannot start at all. Two keys do that, and skipping them produces exactly two
+failures, both measured:
+
+```yaml
+agent:
+  # Where the binary lives. Without it every lens reports
+  # "'claude' is not recognized as an internal or external command".
+  runtime: ["/home/you/.local/bin"]
+  # Names only — the VALUE comes from the environment the daemon holds, so no
+  # key is ever written into this file. Without it a provider that keeps its
+  # login in a credential store answers "Not logged in · Please run /login",
+  # because looply will not grant an agent a credential store.
+  env: ["CLAUDE_CODE_OAUTH_TOKEN"]
+```
+
+Confirm both with `looply doctor --provider`, which spends one model call and
+tells you whether the process actually started, answered, or hung.
+
+## Requirements
+
+- Node 20 or newer
+- A git repository with a clean working tree — a run refuses to start otherwise, because
+  the first discard would destroy uncommitted work
+- At least one check of your own that exits non-zero when it fails. Without one there is
+  nothing for the first key to turn.
+
+## What it is not
+
+- Not a coding agent. It drives the one you already use and is worth nothing without it.
+- Not a replacement for review. It narrows what you review and shows its working.
+- Not free. Every round is agent time, and a check that rejects work has still been paid for.
+
+## Documentation
+
+<https://looply-agent-app.web.app/docs/>
+
+MIT © vuedale

package/dist/.src-hash

@@ -0,0 +1 @@
+0718ecc55a9ad89af6ef6bfb9f39e9139d823f2be48bcd1675cb79cd8be97d7a

package/dist/acceptance-observe.d.ts

@@ -0,0 +1,108 @@
+import { type AcceptanceStepShape, type ObservedProfile } from '@looply/core';
+import type { CommandRunner } from './gate';
+import type { ContainmentProbe } from './untrusted-exec';
+export interface LockIdentity {
+    readonly file: string;
+    readonly digest: string;
+}
+/**
+ * The dependency DECLARATION in a checkout, as `<file>@<sha256:16>`.
+ *
+ * ⚠️ A DECLARATION, NOT AN INSTALLATION — see `deps` below. Returns null when the
+ * project holds no lockfile at all, which is a readable answer and not a
+ * failure: plenty of real projects have none, and a default that demanded one
+ * would refuse them for ever.
+ */
+export declare function readLockIdentity(dir: string): LockIdentity | null;
+export interface EnvironmentSource {
+    /** `process.platform`, injected rather than read, so a test can state it. */
+    readonly platform: string;
+    /** `process.arch`. */
+    readonly arch: string;
+    /** `process.versions.node`. */
+    readonly nodeVersion: string;
+    /** The acceptance map this pass ran under — `cfg.gates`. */
+    readonly gates: readonly AcceptanceStepShape[];
+    /**
+     * `DoctorReport.containment`, or null when nothing asked.
+     *
+     * 🔴 THIS IS THE FACT THE LANE ALREADY COMPUTED AND THREW AWAY.
+     * `integration-deps.ts` mapped the doctor report down to `{name, ok, detail}`
+     * and dropped `containment` with it, so the one question "was there a boundary
+     * around this execution" was answered on every lane pass and recorded nowhere.
+     */
+    readonly containment: ContainmentProbe | null;
+    /** The candidate checkout's own lockfile, or null when it holds none. */
+    readonly lock: LockIdentity | null;
+    /**
+     * Did this checkout receive `node_modules` (or anything else) from the host
+     * rather than installing from its own lockfile?
+     *
+     * 🔴 NOT A FORMALITY, AND THE REASON `deps` EXISTS APART FROM `lock`. The lane
+     * copies `run.carry_into_checkouts` into the candidate's worktree from the
+     * LANE's tree (integration-runtime.ts, `carryIntoCheckout`), so the gate runs
+     * the candidate's lockfile against the host's installed tree. Recording a lock
+     * digest alone would assert a dependency identity the check did not have.
+     */
+    readonly depsCarried: boolean;
+}
+/**
+ * Assemble the observation. PURE: every fact arrives as an argument.
+ *
+ * ⚠️ A FACT THAT COULD NOT BE READ IS `null`, NEVER OMITTED AND NEVER GUESSED.
+ * Absent means nobody asked and `null` means it was asked and could not be read;
+ * the matcher refuses each by its own name, and Rule #1 makes both non-evidence
+ * in strict mode.
+ */
+export declare function observedProfile(src: EnvironmentSource): ObservedProfile;
+/**
+ * The observation for a gate pass in `dir`, reading this process and that
+ * checkout.
+ *
+ * ⚠️ `platform`/`arch`/`nodeVersion` DESCRIBE THE PROCESS THAT RAN THE GATE, and
+ * that is the right answer: the lane runs the candidate's checks in a worktree
+ * on this machine, so this machine is where they happened.
+ */
+export declare function observeAt(dir: string, gates: readonly AcceptanceStepShape[], containment: ContainmentProbe | null, depsCarried: boolean): ObservedProfile;
+/** How long a declared probe may take before it is treated as unreadable. */
+export declare const PROBE_TIMEOUT_MS = 30000;
+/** A probe answer longer than this is a command that misunderstood its job. */
+export declare const PROBE_VALUE_MAX = 200;
+/**
+ * Read the facts this machine cannot read for itself — a database engine and
+ * major version, a migration head, a build target.
+ *
+ * 🔴 EVERY FAILURE IS `null`, WHICH IS "ASKED AND UNREADABLE", AND IN STRICT
+ * MODE THAT IS A REFUSAL. A probe that exits non-zero, times out, or prints
+ * nothing does NOT quietly drop out of the profile — dropping it would read
+ * downstream as "nobody asked", which is a different fact and the softer one.
+ * Fail-closed is the charter's rule for a required fact that cannot be read.
+ *
+ * ⚠️ THE FIRST NON-EMPTY LINE, TRIMMED. A probe is a fact reader, not a report;
+ * anything longer than a short identifier is a command that misunderstood its
+ * job, and truncating silently would make two different databases digest alike.
+ * An over-long answer is `null` for the same reason a crash is.
+ *
+ * ⚠️ RUN UNDER THE SAME CONTAINED RUNNER AS THE GATE, in the candidate's own
+ * checkout. On a platform whose containment backend refuses outright, every
+ * probe answers `null` — which is honest, and is why an owner who declares one
+ * is told by `doctor` before a Start is ever spent on it.
+ */
+export declare function runAcceptanceProbes(probes: readonly {
+    readonly fact: string;
+    readonly run: string;
+}[], runner: CommandRunner, timeoutMs?: number): Promise<Record<string, string | null>>;
+/**
+ * The full observation: the facts this process and checkout can state, plus
+ * whatever the project's declared probes answer.
+ *
+ * ⚠️ PROBE ANSWERS GO THROUGH `normaliseObserved` WITH THE REST, so a probe
+ * cannot invent a fact outside the closed set — a probe declared for
+ * `probe.db-engine` cannot return a `user` key, because it returns a string and
+ * the key is the one the owner declared.
+ */
+export declare function observeAtWithProbes(dir: string, gates: readonly AcceptanceStepShape[], containment: ContainmentProbe | null, depsCarried: boolean, probes: readonly {
+    readonly fact: string;
+    readonly run: string;
+}[], runner: CommandRunner): Promise<ObservedProfile>;
+//# sourceMappingURL=acceptance-observe.d.ts.map

package/dist/acceptance-observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptance-observe.d.ts","sourceRoot":"","sources":["../src/acceptance-observe.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AA0BzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAUjE;AAED,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC9C,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,iBAAiB,GAAG,eAAe,CAavE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,WAAW,EAAE,gBAAgB,GAAG,IAAI,EACpC,WAAW,EAAE,OAAO,GACnB,eAAe,CAUjB;AAED,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,+EAA+E;AAC/E,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,EAClE,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,MAAyB,GACnC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAgBxC;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,WAAW,EAAE,gBAAgB,GAAG,IAAI,EACpC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,EAClE,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,eAAe,CAAC,CAI1B"}

package/dist/acceptance-observe.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROBE_VALUE_MAX = exports.PROBE_TIMEOUT_MS = void 0;
+exports.readLockIdentity = readLockIdentity;
+exports.observedProfile = observedProfile;
+exports.observeAt = observeAt;
+exports.runAcceptanceProbes = runAcceptanceProbes;
+exports.observeAtWithProbes = observeAtWithProbes;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+/**
+ * THE READER FOR RULE #1 — what a gate pass was actually observed to happen
+ * under.
+ *
+ * 🔴 EVERY FACT COMES FROM THIS PROCESS, FROM THE CANDIDATE'S OWN CHECKOUT, OR
+ * FROM THE GATE REPORT. No agent output reaches this file and there is no field
+ * on `IntegrationCandidate` that could supply one — which is the mechanical form
+ * of "no model decides whether its own environment qualifies". The matcher
+ * (`packages/core/src/acceptance-environment.ts`) then decides on the
+ * OBSERVATION IT IS HANDED and never on this host, and a purity spec pins that.
+ *
+ * ⚠️ FACTS ARE COLLECTED WHETHER OR NOT ANYTHING REQUIRES THEM. An observation
+ * is a record for a person to read; `matchProfile` loops over `required`, so a
+ * fact nobody asked for cannot refuse anything. Collecting broadly and matching
+ * narrowly is the whole shape of "irrelevant facts must not invalidate".
+ *
+ * ⚠️ AND NOTHING SECRET IS COLLECTED. The closed list in core is the guard —
+ * `normaliseObserved` drops anything outside it — but the first defence is that
+ * nothing here reads an env var, a credential store or a home directory.
+ */
+/** The lockfiles worth recognising, in the order a project would hold them. */
+const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'npm-shrinkwrap.json'];
+/**
+ * The dependency DECLARATION in a checkout, as `<file>@<sha256:16>`.
+ *
+ * ⚠️ A DECLARATION, NOT AN INSTALLATION — see `deps` below. Returns null when the
+ * project holds no lockfile at all, which is a readable answer and not a
+ * failure: plenty of real projects have none, and a default that demanded one
+ * would refuse them for ever.
+ */
+function readLockIdentity(dir) {
+    for (const file of LOCKFILES) {
+        try {
+            const bytes = (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, file));
+            return { file, digest: (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex').slice(0, 16) };
+        }
+        catch {
+            /* not this one */
+        }
+    }
+    return null;
+}
+/**
+ * Assemble the observation. PURE: every fact arrives as an argument.
+ *
+ * ⚠️ A FACT THAT COULD NOT BE READ IS `null`, NEVER OMITTED AND NEVER GUESSED.
+ * Absent means nobody asked and `null` means it was asked and could not be read;
+ * the matcher refuses each by its own name, and Rule #1 makes both non-evidence
+ * in strict mode.
+ */
+function observedProfile(src) {
+    return (0, core_1.normaliseObserved)({
+        os: src.platform,
+        arch: src.arch,
+        runtime: `node@${src.nodeVersion}`,
+        lock: src.lock === null ? 'none' : `${src.lock.file}@${src.lock.digest}`,
+        deps: src.depsCarried ? 'carried-from-host' : 'from-lock',
+        gates: (0, core_1.acceptanceMapDigest)(src.gates),
+        containment: src.containment === null
+            ? null
+            : `${src.containment.backend}:${src.containment.available ? 'available' : 'unavailable'}`,
+    });
+}
+/**
+ * The observation for a gate pass in `dir`, reading this process and that
+ * checkout.
+ *
+ * ⚠️ `platform`/`arch`/`nodeVersion` DESCRIBE THE PROCESS THAT RAN THE GATE, and
+ * that is the right answer: the lane runs the candidate's checks in a worktree
+ * on this machine, so this machine is where they happened.
+ */
+function observeAt(dir, gates, containment, depsCarried) {
+    return observedProfile({
+        platform: process.platform,
+        arch: process.arch,
+        nodeVersion: process.versions.node,
+        gates,
+        containment,
+        lock: readLockIdentity(dir),
+        depsCarried,
+    });
+}
+/** How long a declared probe may take before it is treated as unreadable. */
+exports.PROBE_TIMEOUT_MS = 30_000;
+/** A probe answer longer than this is a command that misunderstood its job. */
+exports.PROBE_VALUE_MAX = 200;
+/**
+ * Read the facts this machine cannot read for itself — a database engine and
+ * major version, a migration head, a build target.
+ *
+ * 🔴 EVERY FAILURE IS `null`, WHICH IS "ASKED AND UNREADABLE", AND IN STRICT
+ * MODE THAT IS A REFUSAL. A probe that exits non-zero, times out, or prints
+ * nothing does NOT quietly drop out of the profile — dropping it would read
+ * downstream as "nobody asked", which is a different fact and the softer one.
+ * Fail-closed is the charter's rule for a required fact that cannot be read.
+ *
+ * ⚠️ THE FIRST NON-EMPTY LINE, TRIMMED. A probe is a fact reader, not a report;
+ * anything longer than a short identifier is a command that misunderstood its
+ * job, and truncating silently would make two different databases digest alike.
+ * An over-long answer is `null` for the same reason a crash is.
+ *
+ * ⚠️ RUN UNDER THE SAME CONTAINED RUNNER AS THE GATE, in the candidate's own
+ * checkout. On a platform whose containment backend refuses outright, every
+ * probe answers `null` — which is honest, and is why an owner who declares one
+ * is told by `doctor` before a Start is ever spent on it.
+ */
+async function runAcceptanceProbes(probes, runner, timeoutMs = exports.PROBE_TIMEOUT_MS) {
+    const out = {};
+    for (const p of probes) {
+        try {
+            const r = await runner(p.run, timeoutMs);
+            const line = (r.output ?? '')
+                .split('\n')
+                .map((l) => l.trim())
+                .find((l) => l !== '');
+            out[p.fact] = r.ok && !r.timedOut && line !== undefined && line.length <= exports.PROBE_VALUE_MAX ? line : null;
+        }
+        catch {
+            // A runner that throws is a machine that cannot answer, not a fact.
+            out[p.fact] = null;
+        }
+    }
+    return out;
+}
+/**
+ * The full observation: the facts this process and checkout can state, plus
+ * whatever the project's declared probes answer.
+ *
+ * ⚠️ PROBE ANSWERS GO THROUGH `normaliseObserved` WITH THE REST, so a probe
+ * cannot invent a fact outside the closed set — a probe declared for
+ * `probe.db-engine` cannot return a `user` key, because it returns a string and
+ * the key is the one the owner declared.
+ */
+async function observeAtWithProbes(dir, gates, containment, depsCarried, probes, runner) {
+    const core = observeAt(dir, gates, containment, depsCarried);
+    if (probes.length === 0)
+        return core;
+    return (0, core_1.normaliseObserved)({ ...core, ...(await runAcceptanceProbes(probes, runner)) });
+}
+//# sourceMappingURL=acceptance-observe.js.map

package/dist/acceptance-observe.js.map

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

package/dist/agent-cmd.d.ts

@@ -0,0 +1,131 @@
+import type { Item, Status } from '@looply/core';
+import type { LooplyConfig } from './config';
+/**
+ * `looply agent` — the machine-readable surface.
+ *
+ * Everything else in this CLI is written for a person: boxes, colour, a next
+ * step spelled out. This one is written for another program, and the two goals
+ * fight each other badly enough that mixing them produces output neither can
+ * use. So the split is explicit.
+ *
+ * Three promises, because a tool that consumes this has no way to ask:
+ *
+ *  1. `schemaVersion` changes when a field's meaning changes. A consumer can
+ *     refuse to guess rather than silently misread.
+ *  2. Every field is either present or explicitly `null`. Nothing is omitted,
+ *     so `undefined` never has to be told apart from "absent because false".
+ *  3. It exits 0 whenever it could answer at all, including "nothing is
+ *     running". A non-zero exit means the question could not be answered —
+ *     never that the answer was boring.
+ */
+export declare const AGENT_SCHEMA_VERSION = 1;
+export interface AgentQueueItem {
+    id: string;
+    title: string;
+    tag: string;
+    state: string;
+    attempts: number;
+    /** Why the last attempt was thrown away, when there was one. */
+    lastFailure: string | null;
+    evidence: {
+        path: string;
+        line: number | null;
+    }[];
+}
+export interface AgentSnapshot {
+    schemaVersion: number;
+    cliVersion: string;
+    project: {
+        name: string;
+        configured: boolean;
+        id: string | null;
+    };
+    machine: {
+        paired: boolean;
+        id: string | null;
+        serverUrl: string | null;
+    };
+    run: {
+        live: boolean;
+        id: string | null;
+        branch: string | null;
+        startedAt: string | null;
+        endedAt: string | null;
+        stopReason: string | null;
+        /** Whether events are still arriving; null when no run has ever happened. */
+        stale: boolean | null;
+    };
+    round: {
+        n: number | null;
+        itemId: string | null;
+        title: string | null;
+        attempt: number | null;
+        phase: string | null;
+        checks: {
+            name: string;
+            ok: boolean;
+            skipped: boolean;
+            ms: number;
+        }[];
+    } | null;
+    totals: {
+        rounds: number;
+        committed: number;
+        discarded: number;
+        abandoned: number;
+    };
+    queue: {
+        ready: number;
+        draft: number;
+        blocked: number;
+        total: number;
+        items: AgentQueueItem[];
+    };
+    questions: {
+        id: string;
+        text: string;
+        default: string;
+        deadline: string;
+    }[];
+    /** Guidance for a caller deciding what to do next, in machine terms. */
+    suggests: string | null;
+}
+export interface AgentInput {
+    cliVersion: string;
+    config: LooplyConfig | null;
+    status: Status | null;
+    items: readonly Item[];
+    machine: {
+        paired: boolean;
+        id: string | null;
+        serverUrl: string | null;
+    };
+    now: number;
+    staleAfterMs?: number;
+    /** Cap on items included; the counts stay complete regardless. */
+    limit?: number;
+}
+/**
+ * What a caller should probably do next, as a stable token rather than prose.
+ *
+ * Deliberately not a sentence: a program branching on `"scan"` keeps working
+ * when the wording changes, and a program branching on English does not.
+ */
+export declare function suggestion(input: {
+    configured: boolean;
+    live: boolean;
+    ready: number;
+    draft: number;
+    openQuestions: number;
+}): string | null;
+export declare function buildSnapshot(input: AgentInput): AgentSnapshot;
+/** Stable two-space JSON — diffable, and readable when a human ends up reading it. */
+export declare function renderAgentJson(snapshot: AgentSnapshot): string;
+/**
+ * The same snapshot as lines of `key=value`.
+ *
+ * For shell callers, where reaching for `jq` to learn whether a run is going is
+ * more ceremony than the question deserves.
+ */
+export declare function renderAgentText(s: AgentSnapshot): string;
+//# sourceMappingURL=agent-cmd.d.ts.map

package/dist/agent-cmd.d.ts.map

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