waterplane 0.0.1 → 0.1.6

package/packages/host/dist/peers/agentpeer.js

@@ -0,0 +1,249 @@
+/**
+ * The asking agent's way to a peer desktop (docs/analysis/peer-hosts-plan.md): the loopback twin of
+ * `agentintents.ts` — `POST|GET|DELETE /api/agent/peer/<peer>/intents[/<id>]` — and the wiring that
+ * builds the job machine (`jobs.ts`) from the host's own parts.
+ *
+ *  - **Same gate, same refusals.** `agentCallerRefusal` (loopback, no browser, not proxied) and
+ *    `agentBasics` (key, prompt/steps, repo/dir/session) are reused, not copied: an agent that gets
+ *    a sentence from `/api/agent/intents` gets the same sentence here.
+ *  - **Nothing is forwarded that is not pushed.** `branch` must be on `origin` (`git ls-remote`) with
+ *    `commit` reachable from its tip, else a 400 and nothing is sent or written. A retry under a key
+ *    this host already holds answers that job (`existing`) before any git runs.
+ *  - **The peer's clone is the peer's business**: `remote` is `remote.origin.url` AS WRITTEN (never `remote get-url`: it applies `insteadOf`, and the peer's `gitRemoteUrl` would key the repo differently) of the
+ *    asking repo, matched there by `remoteKey`. A body's `peerDir` (a path on the PEER, picking one
+ *    of two clones) is forwarded as the job's `dir`; the body's own `dir`/`repo` are THIS host's.
+ *  - **The report comes back through the intent store** (`jobs.ts`): never a new send path.
+ * Nothing here fires anything or applies a report.
+ */
+import { execFile } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { ORIGIN_PEER_PREFIX, PEER_NAME_RE, PEER_REPORT_MAX_CHARS, makeEnvReader, peerJobId, remoteKey, sessionPickLabel, } from "@waterplane/shared";
+import { addClientBacklogItem, agentBasics, agentCallerRefusal, postClientDraft } from "../agentintents.js";
+import { hostStateDir } from "../branddirs.js";
+import { findTarget } from "../repos.js";
+import { newOutboxPath } from "../files.js";
+import { PeerClient } from "./client.js";
+import { setPeerJobsLedger } from "./routes.js";
+import { PeerJobs } from "./jobs.js";
+export const runGit = (cwd, args) => new Promise((resolve) => {
+    execFile("git", ["-C", cwd, ...args], { timeout: 20_000, maxBuffer: 1 << 20, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }, (err, stdout) => resolve({ ok: !err, out: String(stdout || "").trim() }));
+});
+const BRANCH_RE = /^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]{1,200}$/;
+const COMMIT_RE = /^[0-9a-f]{7,40}$/i;
+/**
+ * Is `commit` on `origin/<branch>`? The full sha, or why not. Asks the REMOTE (`ls-remote`), so a
+ * branch that was only committed locally is refused: the peer fetches from the shared remote.
+ */
+export async function verifyPushed(cwd, branch, commit, git = runGit) {
+    if (!BRANCH_RE.test(branch))
+        return { ok: false, error: "`branch` is not a branch name" };
+    if (!COMMIT_RE.test(commit))
+        return { ok: false, error: "`commit` is a git sha (7-40 hex)" };
+    const local = await git(cwd, ["rev-parse", "--verify", `${commit}^{commit}`]);
+    if (!local.ok || !/^[0-9a-f]{40}$/.test(local.out))
+        return { ok: false, error: `commit ${commit} is not in this repo` };
+    const full = local.out;
+    const remote = await git(cwd, ["ls-remote", "origin", `refs/heads/${branch}`]);
+    if (!remote.ok)
+        return { ok: false, error: "could not ask origin about the branch (ls-remote failed) — nothing was sent" };
+    const tip = /^([0-9a-f]{40})\s/.exec(remote.out)?.[1];
+    if (!tip)
+        return { ok: false, error: `branch ${branch} is not on origin; push first` };
+    if (tip !== full) {
+        const anc = await git(cwd, ["merge-base", "--is-ancestor", full, tip]);
+        if (!anc.ok)
+            return { ok: false, error: `commit ${full.slice(0, 10)} is not on origin/${branch}; push first` };
+    }
+    return { ok: true, commit: full };
+}
+const ROUTE = /^\/api\/agent\/peer\/([^/]+)\/intents(?:\/([^/]+))?$/;
+/** A job as the agent reads it: the state, the peer's words, and — once it is in — the report. */
+export function peerJobView(r) {
+    return {
+        id: r.id, peer: r.peer, state: r.state, branch: r.branch, commit: r.commit,
+        ...(r.closed ? { closed: true } : {}),
+        ...(r.view?.waiting ? { waiting: r.view.waiting } : {}),
+        ...(r.unreachableSince ? { unreachableSince: r.unreachableSince } : {}),
+        ...(r.detail ? { detail: r.detail } : {}),
+        ...(r.view?.sessionId ? { peerSession: r.view.sessionId } : {}),
+        ...(r.reported ? { reported: true } : {}),
+        ...(r.cost ? { cost: r.cost } : {}),
+    };
+}
+/** `true` when the request was this route's (answered, or refused). */
+export function makePeerAgentHandler(d) {
+    return async (req, res, path, _url, io) => {
+        const m = ROUTE.exec(path);
+        if (!m)
+            return false;
+        const { json } = io;
+        const refusal = agentCallerRefusal(req.socket.remoteAddress, req.headers);
+        if (refusal) {
+            json(res, { ok: false, error: refusal }, 403);
+            return true;
+        }
+        const method = req.method ?? "GET";
+        let peer, id;
+        try {
+            peer = decodeURIComponent(m[1]);
+            id = m[2] ? decodeURIComponent(m[2]) : "";
+        }
+        catch {
+            json(res, { ok: false, error: "bad path" }, 400);
+            return true;
+        }
+        if (!PEER_NAME_RE.test(peer)) {
+            json(res, { ok: false, error: "no such peer" }, 404);
+            return true;
+        }
+        const git = d.git ?? runGit;
+        if (method === "POST" && !id) {
+            const body = await io.readJson(req);
+            let cwd = null;
+            if (typeof body?.repo === "string" && body.repo.trim()) {
+                const wt = await d.repoDir(body.repo.trim());
+                if (!wt) {
+                    json(res, { ok: false, error: "unknown repo — ids come from GET /api/repos" }, 404);
+                    return true;
+                }
+                cwd = await d.containRepoDir(wt);
+            }
+            else if (typeof body?.dir === "string" && body.dir.trim())
+                cwd = await d.containRepoDir(body.dir);
+            if ((body?.repo || body?.dir) && !cwd) {
+                json(res, { ok: false, error: "that folder is outside the configured root — nothing was sent" }, 400);
+                return true;
+            }
+            const basics = agentBasics(body, { now: (d.now ?? Date.now)(), cwd, sessionCwd: d.sessionCwd, intent: () => undefined });
+            if ("refused" in basics) {
+                json(res, { ok: false, error: basics.refused }, 400);
+                return true;
+            }
+            const key = basics.key;
+            const prior = d.jobs.get(peerJobId(peer, key));
+            const answer = (r, existing) => ({
+                ok: true, id: r.id, state: r.state, peer, existing, fires: `sent to ${peer} — waiting`,
+                note: existing ? "already sent under this key — nothing new was forwarded" : `the report comes back as a prompt in this session; DELETE /api/agent/peer/${peer}/intents/${r.id} calls it off here`,
+            });
+            if (prior) {
+                json(res, answer(prior, true));
+                return true;
+            }
+            const branch = typeof body?.branch === "string" ? body.branch.trim() : "";
+            const commit = typeof body?.commit === "string" ? body.commit.trim() : "";
+            const pushed = await verifyPushed(basics.cwd, branch, commit, git);
+            if (!pushed.ok) {
+                json(res, { ok: false, error: pushed.error }, 400);
+                return true;
+            }
+            const url0 = await git(basics.cwd, ["config", "--get", "remote.origin.url"]);
+            if (!url0.ok || !remoteKey(url0.out)) {
+                json(res, { ok: false, error: "this repo's origin remote cannot be read as a shared remote — the peer could not find the repo" }, 400);
+                return true;
+            }
+            const req2 = {
+                key, remote: url0.out, branch, commit: pushed.commit, steps: basics.steps,
+                ...(basics.label ? { label: basics.label } : {}),
+                ...(typeof body.closeWhenDone === "boolean" ? { closeWhenDone: body.closeWhenDone } : {}),
+                ...(typeof body.reportArtifacts === "boolean" ? { reportArtifacts: body.reportArtifacts } : {}),
+                ...(typeof body.peerDir === "string" && body.peerDir.trim() ? { dir: body.peerDir.trim() } : {}),
+            };
+            // The asking session: the one named, else the newest live one in this cwd; none ⇒ the backlog gets the report.
+            const sessionId = basics.sessionId ?? d.runningSessionFor(basics.cwd) ?? undefined;
+            // Its label rides to the peer, so the job's session there can say whose work it is.
+            const askerLabel = sessionId ? d.sessionLabel?.(sessionId)?.replace(/\s+/g, " ").trim().slice(0, 80) : undefined;
+            if (askerLabel)
+                req2.askerLabel = askerLabel;
+            // Re-read after every await: submit is synchronous, and answers the same record to a racing twin.
+            const r = d.jobs.submit({ peer, req: req2, cwd: basics.cwd, sessionId });
+            if (!r.ok) {
+                json(res, { ok: false, error: r.error }, r.status);
+                return true;
+            }
+            json(res, answer(r.rec, r.existing));
+            return true;
+        }
+        if (method === "GET" && !id) {
+            json(res, { ok: true, jobs: d.jobs.list().filter((r) => r.peer === peer).map(peerJobView) });
+            return true;
+        }
+        if (id && (method === "GET" || method === "DELETE")) {
+            const r = d.jobs.get(id);
+            if (!r || r.peer !== peer) {
+                json(res, { ok: false, error: "no such job" }, 404);
+                return true;
+            }
+            if (method === "DELETE")
+                d.jobs.cancel(id);
+            json(res, { ok: true, ...peerJobView(d.jobs.get(id)), ...(method === "DELETE" ? { calledOff: true } : {}) });
+            return true;
+        }
+        json(res, { ok: false, error: `${method} is not a verb here — POST /api/agent/peer/${peer}/intents, GET …/intents[/<id>], DELETE …/intents/<id>` }, 405);
+        return true;
+    };
+}
+// ── the seam api.ts mounts, and the boot wiring main.ts calls ────────────────
+let registered;
+/** Mounted in `api.ts`; a no-op until `startPeerJobs` has run (and under `--doctor`, forever). */
+export async function handlePeerAgent(req, res, path, url, io) {
+    return registered ? registered(req, res, path, url, io) : false;
+}
+/** The bytes of a peer's artifact into the repo's outbox as `peer-<peer>-<stem>`; the repo-relative path. */
+export function saveOutboxArtifact(cwd, peer, name, bytes) {
+    const base = basename(String(name).replace(/\\/g, "/"));
+    const ext0 = extname(base);
+    const ext = /^\.[A-Za-z0-9]{1,8}$/.test(ext0) ? ext0.toLowerCase() : ".bin";
+    const stem = (ext0 ? base.slice(0, -ext0.length) : base).replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^[._]+/, "").slice(0, 60) || "file";
+    try {
+        const p = newOutboxPath(cwd, `peer-${peer}-${stem}`, ext);
+        writeFileSync(p.full, bytes);
+        return p.relPath;
+    }
+    catch {
+        return null;
+    }
+}
+/** Build the job machine from the host's parts, mount the route, resume open jobs. Called from `main.ts` after `intents.start()`. */
+export function startPeerJobs(ctx) {
+    if (ctx.DOCTOR)
+        return null; // a doctor run never polls a peer or posts a row
+    const { envInt } = makeEnvReader(process.env, () => undefined);
+    const jobs = new PeerJobs({
+        file: join(hostStateDir(ctx.ROOT), "peer-jobs.json"),
+        store: ctx.peers,
+        client: new PeerClient(),
+        now: Date.now,
+        pollMs: Math.max(500, envInt("PEER_POLL_MS", 5000)),
+        reportMax: Math.max(500, envInt("PEER_REPORT_MAX_CHARS", PEER_REPORT_MAX_CHARS)),
+        schedule: (fn, ms) => { const t = setTimeout(fn, ms); t.unref(); return { cancel: () => clearTimeout(t) }; },
+        sessionAlive: (id) => !!ctx.sessions.get(id)?.running,
+        setPeerWait: (id, w) => ctx.sessions.setPeerFacts(id, { peerWait: w }),
+        setPeerJobs: (id, list) => ctx.sessions.setPeerFacts(id, { peerJobs: list }),
+        intentState: (id) => ctx.intents.get(id)?.state,
+        postReport: async (draft, peer) => {
+            const r = await postClientDraft({ intents: ctx.intents, containRepoDir: (x) => ctx.containRepoDir(x) }, draft, { origin: ORIGIN_PEER_PREFIX + peer });
+            return r.ok ? { ok: true, existing: r.existing } : { ok: false, reason: r.reason };
+        },
+        addBacklog: async (p) => {
+            const r = await addClientBacklogItem({ containRepoDir: (x) => ctx.containRepoDir(x), backlog: ctx.backlog }, { repoDir: p.cwd, text: p.text, label: p.label, id: p.id, origin: ORIGIN_PEER_PREFIX + p.peer, manual: true });
+            return r.ok;
+        },
+        saveArtifact: saveOutboxArtifact,
+        notify: (title, body, backlog) => ctx.notify("backlog", { title, body, ...(backlog ? { backlog } : {}) }),
+        log: (m) => console.warn(m),
+    });
+    registered = makePeerAgentHandler({
+        jobs,
+        containRepoDir: (x) => ctx.containRepoDir(x),
+        repoDir: async (id) => (await findTarget(ctx.ROOT, id))?.worktreePath ?? null,
+        sessionCwd: (id) => { const s = ctx.sessions.get(id); return s && s.running ? s.cwd : null; },
+        runningSessionFor: (dir) => ctx.sessions.runningSessionFor(dir),
+        sessionLabel: (id) => { const s = ctx.sessions.get(id); return s ? sessionPickLabel(s) : null; },
+    });
+    // The phone's read of this ledger (`GET /api/peerjobs`, trusted path — `routes.ts`).
+    setPeerJobsLedger(() => jobs.ledger());
+    jobs.start();
+    return jobs;
+}
+//# sourceMappingURL=agentpeer.js.map

package/packages/host/dist/peers/agentpeer.js.map

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

package/packages/host/dist/peers/client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Calling a peer (docs/analysis/peer-hosts-plan.md): the asking side's HTTP to another waterplane
+ * host — `hello`, post a job, read a job, fetch an artifact. Every call carries the bearer token
+ * and `PEER_API_HEADER`, has a timeout, and answers a tagged result instead of throwing, so the
+ * state machine in `jobs.ts` decides what each outcome means.
+ *
+ * Outcomes: `ok` (a body), `unreachable` (no answer, a timeout or a 5xx — never a verdict about
+ * the job), `mismatch` (409: the sentence naming both versions), `denied` (403: not paired) and
+ * `rejected` (any other 4xx, with the peer's own sentence). Nothing here retries or keeps state
+ * except the 10-minute `hello` cache.
+ */
+import { type PeerHello, type PeerJobRequest, type PeerJobView } from "@waterplane/shared";
+export type PeerReply<T> = {
+    kind: "ok";
+    body: T;
+} | {
+    kind: "unreachable";
+    error: string;
+} | {
+    kind: "mismatch";
+    text: string;
+} | {
+    kind: "denied";
+    text: string;
+} | {
+    kind: "rejected";
+    status: number;
+    text: string;
+};
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    ok: boolean;
+    json(): Promise<any>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+export interface PeerTarget {
+    name: string;
+    addr: string;
+    token: string;
+}
+export declare const HELLO_TTL_MS: number;
+export declare class PeerClient {
+    private readonly f;
+    private readonly now;
+    private hellos;
+    constructor(f?: FetchLike, now?: () => number);
+    private call;
+    /** `hello`, cached 10 minutes per peer — only a good answer is cached. */
+    hello(t: PeerTarget): Promise<PeerReply<PeerHello>>;
+    /** `hello` past the cache: what the peer says NOW (a sign-in shows up on the next look). */
+    helloFresh(t: PeerTarget): Promise<PeerReply<PeerHello>>;
+    postJob(t: PeerTarget, req: PeerJobRequest): Promise<PeerReply<PeerJobView>>;
+    getJob(t: PeerTarget, id: string): Promise<PeerReply<PeerJobView>>;
+    getArtifact(t: PeerTarget, id: string, name: string): Promise<PeerReply<ArrayBuffer>>;
+}

package/packages/host/dist/peers/client.js

@@ -0,0 +1,96 @@
+/**
+ * Calling a peer (docs/analysis/peer-hosts-plan.md): the asking side's HTTP to another waterplane
+ * host — `hello`, post a job, read a job, fetch an artifact. Every call carries the bearer token
+ * and `PEER_API_HEADER`, has a timeout, and answers a tagged result instead of throwing, so the
+ * state machine in `jobs.ts` decides what each outcome means.
+ *
+ * Outcomes: `ok` (a body), `unreachable` (no answer, a timeout or a 5xx — never a verdict about
+ * the job), `mismatch` (409: the sentence naming both versions), `denied` (403: not paired) and
+ * `rejected` (any other 4xx, with the peer's own sentence). Nothing here retries or keeps state
+ * except the 10-minute `hello` cache.
+ */
+import { PEER_API_HEADER, PEER_API_VERSION, peerVersionMismatchText, } from "@waterplane/shared";
+const JSON_TIMEOUT_MS = 10_000;
+const ARTIFACT_TIMEOUT_MS = 60_000;
+export const HELLO_TTL_MS = 10 * 60_000;
+export class PeerClient {
+    f;
+    now;
+    hellos = new Map();
+    constructor(f = (u, i) => fetch(u, i), now = Date.now) {
+        this.f = f;
+        this.now = now;
+    }
+    async call(t, method, path, body, timeout, raw) {
+        let r;
+        try {
+            r = await this.f(`http://${t.addr}${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${t.token}`,
+                    [PEER_API_HEADER]: String(PEER_API_VERSION),
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: AbortSignal.timeout(timeout),
+            });
+        }
+        catch (e) {
+            return { kind: "unreachable", error: String(e?.message || e) };
+        }
+        if (r.status >= 500)
+            return { kind: "unreachable", error: `${t.name} answered ${r.status}` };
+        if (r.ok && raw) {
+            try {
+                return { kind: "ok", body: (await r.arrayBuffer()) };
+            }
+            catch (e) {
+                return { kind: "unreachable", error: String(e?.message || e) };
+            }
+        }
+        let j = null;
+        try {
+            j = await r.json();
+        }
+        catch { /* a body that is not JSON says nothing */ }
+        if (r.status === 409) {
+            const theirs = Number(j?.peerApi);
+            const text = Number.isInteger(theirs) && theirs !== PEER_API_VERSION
+                ? peerVersionMismatchText(t.name, PEER_API_VERSION, theirs)
+                : String(j?.error || `${t.name} refused the peer API version`);
+            return { kind: "mismatch", text };
+        }
+        if (r.status === 403)
+            return { kind: "denied", text: `${t.name} says this host is not paired` };
+        if (!r.ok)
+            return { kind: "rejected", status: r.status, text: typeof j?.error === "string" && j.error ? j.error : `${t.name} answered ${r.status}` };
+        return { kind: "ok", body: j };
+    }
+    /** `hello`, cached 10 minutes per peer — only a good answer is cached. */
+    async hello(t) {
+        const c = this.hellos.get(t.name);
+        if (c && this.now() - c.at < HELLO_TTL_MS)
+            return { kind: "ok", body: c.hello };
+        const r = await this.call(t, "GET", "/api/peer/hello", undefined, JSON_TIMEOUT_MS);
+        if (r.kind === "ok")
+            this.hellos.set(t.name, { at: this.now(), hello: r.body });
+        else
+            this.hellos.delete(t.name);
+        return r;
+    }
+    /** `hello` past the cache: what the peer says NOW (a sign-in shows up on the next look). */
+    helloFresh(t) {
+        this.hellos.delete(t.name);
+        return this.hello(t);
+    }
+    postJob(t, req) {
+        return this.call(t, "POST", "/api/peer/jobs", req, JSON_TIMEOUT_MS);
+    }
+    getJob(t, id) {
+        return this.call(t, "GET", `/api/peer/jobs/${encodeURIComponent(id)}`, undefined, JSON_TIMEOUT_MS);
+    }
+    getArtifact(t, id, name) {
+        return this.call(t, "GET", `/api/peer/jobs/${encodeURIComponent(id)}/artifact?name=${encodeURIComponent(name)}`, undefined, ARTIFACT_TIMEOUT_MS, true);
+    }
+}
+//# sourceMappingURL=client.js.map

package/packages/host/dist/peers/client.js.map

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

package/packages/host/dist/peers/jobs.d.ts

@@ -0,0 +1,140 @@
+import { type IntentDraft, type PeerJobLedgerRow, type PeerJobRecord, type PeerJobSummary, type PeerJobRequest, type SessionInfo } from "@waterplane/shared";
+import type { PeerClient } from "./client.js";
+import type { PeerStore } from "./store.js";
+/** What the ledger keeps beyond `PeerJobRecord` — additive, so a ledger from a build without it still reads. */
+export interface PeerJobRec extends PeerJobRecord {
+    /** The forward, minus `from` (the peer names us; filled from `hello` at send). */
+    req: Omit<PeerJobRequest, "from">;
+    /** The peer has the job (a POST was answered). */
+    sent?: boolean;
+    /** Artifacts landed in the asking repo. */
+    fetched?: {
+        name: string;
+        relPath: string;
+    }[];
+    notFetched?: {
+        name: string;
+        why: string;
+    }[];
+    /** Index of the next artifact to fetch (so a restart resumes mid-list). */
+    artIdx?: number;
+    artTries?: number;
+    /** The report row was posted (or the backlog fallback written). */
+    reported?: boolean;
+    fellBack?: boolean;
+    /** Nothing more to do: the report settled, or the job was called off. */
+    closed?: boolean;
+}
+export type PeerWait = NonNullable<SessionInfo["peerWait"]>;
+export interface PeerJobsDeps {
+    /** `<state dir>/peer-jobs.json`. */
+    file: string;
+    store: Pick<PeerStore, "outbound">;
+    client: Pick<PeerClient, "hello" | "postJob" | "getJob" | "getArtifact">;
+    now(): number;
+    /** Poll period while running; 60 s is the unreachable ceiling. */
+    pollMs: number;
+    reportMax: number;
+    /** Arm the next tick; the default is an unref'd `setTimeout`. */
+    schedule(fn: () => void, ms: number): {
+        cancel(): void;
+    };
+    sessionAlive(id: string): boolean;
+    setPeerWait(sessionId: string, w: PeerWait | null): void;
+    /** Every job the session delegated, open or settled (`SessionInfo.peerJobs`); [] clears. Optional: absent = not published. */
+    setPeerJobs?(sessionId: string, jobs: PeerJobSummary[]): void;
+    /** The intent store's state for an id, or undefined when it holds none. */
+    intentState(id: string): string | undefined;
+    /** `postClientDraft` with `origin: "peer:<peer>"`. */
+    postReport(draft: IntentDraft, peer: string): Promise<{
+        ok: true;
+        existing: boolean;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** `addClientBacklogItem(…, {manual: true})`. */
+    addBacklog(p: {
+        cwd: string;
+        text: string;
+        label: string;
+        id: string;
+        peer: string;
+    }): Promise<boolean>;
+    /** Write bytes into the repo's outbox as `peer-<peer>-<stem>`; the repo-relative path, or null. */
+    saveArtifact(cwd: string, peer: string, name: string, bytes: Buffer): string | null;
+    notify(title: string, body: string, backlog?: {
+        cwd: string;
+        ids: string[];
+    }): void;
+    log?(msg: string): void;
+}
+export declare const UNREACHABLE_CEILING_MS = 60000;
+/** Newest jobs one session lists; older ones stay in the ledger and the Activity sheet. */
+export declare const SESSION_JOBS_MAX = 12;
+export declare class PeerJobs {
+    private readonly d;
+    private recs;
+    private nextAt;
+    private fails;
+    private busy;
+    private timer;
+    private started;
+    constructor(d: PeerJobsDeps);
+    private load;
+    private persist;
+    get(id: string): PeerJobRec | undefined;
+    list(): PeerJobRec[];
+    isOpen(r: PeerJobRec): boolean;
+    /** One job as a session lists it. */
+    summary(r: PeerJobRec): PeerJobSummary;
+    /** The ledger as the phone reads it (`GET /api/peerjobs`), newest first. No token, no report text. */
+    ledger(): PeerJobLedgerRow[];
+    /** Resume after a restart: re-set `peerWait` on surviving sessions, poll again. Zero traffic with no open job. */
+    start(): void;
+    stop(): void;
+    /**
+     * Take a job. An id this ledger already holds answers THAT record (`existing`) and forwards
+     * nothing; the ledger is written before the first forward.
+     */
+    submit(p: {
+        peer: string;
+        req: Omit<PeerJobRequest, "from">;
+        cwd: string;
+        sessionId?: string;
+    }): {
+        ok: true;
+        rec: PeerJobRec;
+        existing: boolean;
+    } | {
+        ok: false;
+        error: string;
+        status: number;
+    };
+    /** A person's DELETE: ends the job on this side without a report. The peer's own row is left to run. */
+    cancel(id: string): PeerJobRec | undefined;
+    /** Advance every due job once. Public so tests (and the timer) drive it. */
+    tick(): Promise<void>;
+    private later;
+    private arm;
+    private pollEvery;
+    /** `SessionInfo.peerJobs` for the asking session: every job it sent, open or closed, oldest first. */
+    private syncJobs;
+    private syncWait;
+    private close;
+    private advance;
+    private send;
+    private poll;
+    /** What a non-ok reply means. Unreachable is never a verdict; a refusal is. */
+    private onBad;
+    private applyView;
+    /** A verdict reached without the peer's say (or with a sentence of ours): terminal, reported like any other. */
+    private settleLocally;
+    private finish;
+    /** false = try again later (an unreachable peer mid-list). */
+    private fetchArtifacts;
+    private promptOf;
+    private report;
+    /** A manual backlog row and a notification: a sentence and a row, never a guess at another session. */
+    private fallBack;
+}