looply-cli 0.0.0-stage → 0.3.0

package/dist/server-client.d.ts

@@ -0,0 +1,766 @@
+import type { RunDelivery } from './run-refusal-marks';
+import type { Attestation, Classification, CoverageKind, Disposition, RequirementCoverage, Source, SourceKind, SourceStatement } from '@looply/core';
+import type { AnyEvent, Goal, GoalAutonomyState, GoalState, MachineSettlableState } from '@looply/core';
+import type { IngestAck } from './uploader';
+/**
+ * The machine's client for the looply server.
+ *
+ * Every failure here must be survivable: the server going away is a degraded
+ * experience, never a stopped run. A run that dies because a relay is down is
+ * strictly worse than one that keeps working and reports late.
+ */
+export declare class ServerError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined);
+    /** The token was revoked or expired. Retrying will not help. */
+    get isAuth(): boolean;
+    /** No response at all — offline, DNS, timeout. Worth retrying later. */
+    get isOffline(): boolean;
+}
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    ok: boolean;
+    text(): Promise<string>;
+}>;
+export interface ServerClientOptions {
+    baseUrl: string;
+    token?: string;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+}
+export declare class ServerClient {
+    private readonly opts;
+    private readonly baseUrl;
+    constructor(opts: ServerClientOptions);
+    withToken(token: string): ServerClient;
+    private request;
+    pairStart(machineName: string): Promise<{
+        pairCode: string;
+        qrPayload: string;
+        expiresAt: string;
+        machineId: string;
+    }>;
+    pairPoll(machineId: string): Promise<{
+        status: "pending" | "claimed";
+        machineToken?: string;
+    }>;
+    /**
+     * One heartbeat, and the cadence the SERVER wants back.
+     *
+     * 🔴 THIS TYPE USED TO SAY `{ ok: boolean; nextBeatS?: number }` AND BOTH
+     * FIELDS WERE INVENTED. The route returns `{ ttlS, refreshS }`, and
+     * `MachinesService` says why in its own words: "the cadence is server-owned,
+     * so tuning the TTL never requires shipping a new CLI."
+     *
+     * ⚠️ THAT PROPERTY DOES NOT CURRENTLY HOLD, AND THE WRONG TYPE IS WHY. The
+     * daemon paces itself on `DEFAULT_HEARTBEAT_MS = 15_000` (`daemon.ts`) and
+     * discards this response entirely — it could not have used `refreshS`,
+     * because the type it was handed did not name it. Correcting the type does not
+     * by itself wire the cadence up; it makes wiring it possible, and stops the
+     * next caller trusting two fields that never arrive.
+     *
+     * Found by `daemon-client-flagship.e2e.spec.ts` asking a real server, after
+     * two existing specs that inject a fake `fetch` had agreed with the client for
+     * as long as it had been wrong.
+     */
+    heartbeat(machineId: string, cliVersion: string): Promise<{
+        ttlS: number;
+        refreshS: number;
+    }>;
+    registerProject(input: {
+        machineId: string;
+        name: string;
+        repoPathHash: string;
+    }): Promise<{
+        project: {
+            id: string;
+        };
+        created: boolean;
+    }>;
+    postEvents(projectId: string, events: readonly AnyEvent[]): Promise<IngestAck>;
+    /**
+     * The effective settings for a project, each tagged with where it came from.
+     * `from: 'default'` means nobody chose it — see settings-overlay.ts for why
+     * that distinction is the whole safety of this feature.
+     */
+    projectSettings(projectId: string): Promise<{
+        settings: {
+            key: string;
+            value: unknown;
+            from: string;
+        }[];
+    }>;
+    /**
+     * The goals the server holds for a project.
+     *
+     * Read-only, and there is deliberately no create/amend counterpart here. The
+     * server is authoritative for goal intent — a person typed it on a phone that
+     * may be the only thing awake — so the machine mirrors it and never writes
+     * back. With no local writer there is no merge to get wrong.
+     *
+     * A machine token reaches this without holding a grant: the daemon is not a
+     * person, and project-access already lets a machine read its own projects.
+     */
+    /**
+     * The exemptions a person has granted on this project, unexpired.
+     *
+     * 🔴 THE SOURCE HALF OF A LINK THAT DID NOT EXIST. `looply run` wired neither
+     * a source of grants nor a sink for spent ones, so no grant ever reached a
+     * gate from a run: the gate's validity check, the core model, the server's
+     * grant and list routes and the commit trailer line were all built and tested
+     * around a door nothing could open.
+     *
+     * ⚠️ NO NEW BACKEND SEMANTICS. This is the route the phone already reads, and
+     * a MACHINE principal is already permitted on it — `ProjectAccessService`
+     * admits `principal.kind === 'machine'` when the machine owns the project.
+     * Nothing server-side changed to make this possible.
+     *
+     * Project-scoped by construction, so a grant cannot cross into another
+     * project: the id in the path is the only project this answers for.
+     */
+    projectExemptions(projectId: string): Promise<{
+        exemptions: ServerExemption[];
+    }>;
+    projectGoals(projectId: string): Promise<{
+        goals: Goal[];
+    }>;
+    /**
+     * Set a goal, from the machine that holds the repository.
+     *
+     * The same route the phone posts to, with the same validators — there is no
+     * second goal-creation path, and adding one would mean two answers to what a
+     * goal is allowed to be. The server derives `createdBy` from the token and
+     * records a machine as a machine; nothing here may claim to be a person.
+     *
+     * ⚠️ IDEMPOTENT ON `clientRef` WITHIN THE PROJECT, and the answer says which
+     * happened. A caller that retries after a timeout must read `deduplicated`
+     * rather than assume it made a second goal — the field exists because
+     * inferring it from a status code is how a client ends up believing it did.
+     */
+    createGoal(projectId: string, input: {
+        clientRef: string;
+        text: string;
+        dependsOn?: readonly string[];
+        surfaces?: readonly string[];
+        requirements?: readonly {
+            sourceId: string;
+            ordinal: number;
+        }[];
+    }): Promise<{
+        goal: Goal;
+        deduplicated: boolean;
+    }>;
+    /**
+     * Hand a document to a project, from the machine that holds it.
+     *
+     * The server keys this on the content's sha256 AND on `clientRef`; the CLI
+     * derives the key from the sha, so the same file twice is the same request
+     * twice and the answer says `deduplicated`. Admitted for the project this
+     * machine drives, and refused for any other.
+     */
+    createSource(projectId: string, input: {
+        clientRef: string;
+        name: string;
+        kind: SourceKind;
+        /** The document, for the text kinds. */
+        content?: string;
+        /** The text layer page by page, for a pdf — read here, on the machine that holds the file. */
+        pages?: {
+            page: number;
+            text: string;
+        }[];
+        /** For a pdf: the sha256 of the file the pages came from. */
+        originSha256?: string;
+    }): Promise<{
+        source: Source;
+        statements: SourceStatement[];
+        deduplicated: boolean;
+    }>;
+    /**
+     * What the items of one goal CLAIM to serve, and which gate step each claim
+     * says would prove it.
+     *
+     * ⚠️ CLAIMS, NOT COVERAGE. `requirementReceipts` decides what a receipt may
+     * speak for, here on the machine, because deciding it needs the gate record
+     * of the tree being judged and the server has never seen one.
+     */
+    goalServings(projectId: string, goalId: string): Promise<{
+        servings: ServingRow[];
+    }>;
+    /** One source, verbatim, with its anchored statements, what each one IS, and where each requirement stands. */
+    sourceDetail(projectId: string, sourceId: string): Promise<{
+        source: Source;
+        statements: SourceStatement[];
+        classifications: Classification[];
+        classifierVersion: number | null;
+        dispositions: Disposition[];
+        reconciledAt: {
+            treeSha: string;
+            reconcilerVersion: number;
+            createdAt: string;
+        } | null;
+        /** What people attested. The daemon reads these; it can never write one (a machine token is refused). */
+        attestations: Attestation[];
+    }>;
+    /** What is covered and by whom, for one source — a read the machine may make about its own project. */
+    coverage(projectId: string, sourceId: string): Promise<{
+        sourceId: string;
+        name: string;
+        reconciledAt: {
+            treeSha: string;
+            reconcilerVersion: number;
+            createdAt: string;
+        } | null;
+        requirements: RequirementCoverage[];
+        tally: Record<CoverageKind, number>;
+    }>;
+    /**
+     * Record where each requirement stands against the repository, as measured
+     * HERE against this machine's project index at HEAD's tree. The server
+     * stores it verbatim, once per (tree, version); the same tree again answers
+     * the rows on record. Admitted for the project this machine drives.
+     */
+    reconcileSource(projectId: string, sourceId: string, input: {
+        treeSha: string;
+        reconcilerVersion: number;
+        dispositions: Disposition[];
+    }): Promise<{
+        dispositions: Disposition[];
+        treeSha: string;
+        reconcilerVersion: number;
+        created: boolean;
+    }>;
+    /**
+     * Raise a structured question, and get the row back so the asker knows its id.
+     *
+     * 🔴 THE ROUTE EXISTED FROM THE START AND NOTHING EVER CALLED IT. `config.ts`
+     * has warned since M6-20 that `on_partial: ask` — the DEFAULT — could not ask,
+     * so a partial proof was discarded with a log line while the server held the
+     * whole mechanism: options, a default, a deadline, first-answer-wins under a
+     * Redis claim, and a sweep that defaults through the very path a person takes.
+     *
+     * ⚠️ MACHINE-ONLY AT THE SERVER, AND FOR THE REASON THE CONTROLLER GIVES: a
+     * question is a prompt a person is asked to authorise something, and being
+     * able to write to that inbox from outside the machine is the whole attack.
+     */
+    askQuestion(input: {
+        projectId: string;
+        runId?: string;
+        kind: string;
+        text: string;
+        options: readonly string[];
+        default: string;
+        deadline: string;
+    }): Promise<ServerQuestion>;
+    /**
+     * One question of one project, answered or not.
+     *
+     * 🔴 `listOpen` DROPS AN ANSWERED QUESTION, so a loop watching that list saw
+     * its own question vanish and never learned which way it went. §6.C asks for
+     * an answer that *"can resume exact work"*, and exact work needs the answer
+     * rather than its absence.
+     *
+     * ⚠️ NOT `question()`, AND THE NAME IS NOT AN ACCIDENT. `client-reachability`
+     * decides “does a consumer exist” by searching for `.<name>(` across the CLI,
+     * which cannot see WHICH object is being called — and readline's asker has a
+     * `.question(` in two files. A client method called `question` would have read
+     * as called for ever, by nothing.
+     */
+    questionById(projectId: string, questionId: string): Promise<{
+        question: ServerQuestion;
+    }>;
+    /** What a project has been given, newest first, without content. */
+    /**
+     * Every session-control grant this project has issued.
+     *
+     * 🔴 A READER, AND DELIBERATELY NO ISSUER. `session-grants.controller.ts`
+     * stamps `createdBy` from the TOKEN's principal and refuses a caller without a
+     * device token, so a machine that posted here would be recorded as the
+     * authorizer of its own authority. Issuing is a person's act; this reads the
+     * result of one.
+     */
+    sessionGrants(projectId: string): Promise<{
+        grants: ServerSessionGrant[];
+    }>;
+    /**
+     * Record that a session acknowledged a grant, and through which channel.
+     *
+     * ⚠️ THE CHANNEL IS CLAIMED, NOT PROVED, WHICH IS WHY IT IS RECORDED RATHER
+     * THAN TRUSTED. A session's adapter and a person's terminal hold the same
+     * device token — a token says which DEVICE spoke, never which program.
+     * `controlVerdict` in core then refuses anything that is not `adapter`, which
+     * turns a person's attempt into a fact on the record instead of an inference
+     * nobody can check.
+     */
+    acknowledgeSessionGrant(projectId: string, grantId: string, ack: {
+        handshakeNonce: string;
+        sessionId: string;
+        workspace: string;
+        repositoryId: string;
+        scope: readonly string[];
+        via: 'adapter' | 'operator';
+    }): Promise<{
+        grant: ServerSessionGrant;
+    }>;
+    /**
+     * Write the effect of an approved `goal.depends`, as the machine carrying it out.
+     *
+     * 🔴 THIS REPLACES A METHOD THAT COULD NEVER WORK FROM HERE. It sent
+     * `PATCH /goals/:goalId` — a PERSON's route — with this client's MACHINE
+     * token, and the server refused it every time (403, measured 2026-09-24).
+     * This client is only ever a machine's, so a method on it that needs a
+     * device token is a method with no caller that can succeed. The governed
+     * route admits the machine only for an execution it began, still
+     * executing, whose server-held action is exactly this edge; the body is
+     * checked against that action, never trusted.
+     */
+    applyGovernedGoalEdge(projectId: string, executionId: string, edge: {
+        goalId: string;
+        version: number;
+        dependsOn: readonly string[];
+    }): Promise<{
+        goal: Goal;
+    }>;
+    sources(projectId: string): Promise<{
+        sources: Omit<Source, "content">[];
+    }>;
+    /**
+     * What the server believes about a goal's pursuits, newest first.
+     *
+     * RECONCILIATION. This machine holds grants in its own store, and the server
+     * can end one without telling it: a person taps Stop, or the goal is edited
+     * and the grant is superseded. Without a way to read back, a machine would go
+     * on spending Starts against a permission that had been withdrawn -- and the
+     * person who withdrew it would watch it keep working.
+     *
+     * A machine token reaches this without holding a grant, the same way it reads
+     * the goal mirror: project-access lets a machine read its own project. That
+     * one route serves the phone and the daemon, which is why it had to declare a
+     * read policy -- guarded and declaring none, it was Forbidden to both.
+     */
+    goalAutonomy(projectId: string, goalId: string): Promise<{
+        autonomy: ServerAutonomy[];
+        /** The goal as it stands NOW. Null when the server has no such goal. */
+        goal: {
+            version: number;
+            state: GoalState;
+        } | null;
+    }>;
+    /**
+     * Say where a pursuit came to rest.
+     *
+     * The server knows it authorized one; only this machine knows whether the
+     * goal was met, whether a person is needed, or whether the budget ran out.
+     *
+     * BY CONTROLLER ID, not by goal and version. Since re-authorization began
+     * minting generations, C1 and C2 can both be G@8 — and a stale report from a
+     * dead generation addressed by goal would land on the grant a person had just
+     * created, ending their fresh night with a conclusion about a different one.
+     *
+     * `version` is the OCC token from the read above and is not optional: a
+     * person may have stopped the pursuit while this machine was deciding, and a
+     * report that lost that race must be told rather than allowed to rewrite
+     * their ending as "the machine finished".
+     *
+     * The state is narrowed to what a machine can PROVE about itself.
+     * `cancelled` is not in that set: it means a person stopped this, and the
+     * machine does not get to say so.
+     */
+    settleGoalAutonomy(projectId: string, controllerId: string, 
+    /** `delivery` (L4b): what key 2 confirmed, on a `satisfied` settle only. */
+    input: {
+        version: number;
+        state: MachineSettlableState;
+        reason?: string;
+        delivery?: RunDelivery;
+    }): Promise<{
+        autonomy: ServerAutonomy;
+    }>;
+    /**
+     * Ask for an exact action to be approved, and never twice.
+     *
+     * IDEMPOTENT ON `clientRef`, which is what makes this callable from a machine
+     * that cannot tell a lost response from a lost request. The server answers
+     * the same row for the same key and says, in `deduplicated`, which of the two
+     * happened — so a retry after a timeout recovers the approval that already
+     * exists instead of raising a second one nobody asked for.
+     *
+     * `context` says which pursuit is asking. The machine names it from its own
+     * trusted run context and the server checks every part against the database;
+     * nothing here is taken on trust, which is why this method does not validate
+     * it either. Composing the URL and parsing the reply is the whole job.
+     *
+     * There is deliberately no counterpart that decides one. A machine that could
+     * answer its own request is a machine nobody is supervising.
+     */
+    createApproval(projectId: string, input: {
+        clientRef: string;
+        actionRequest: unknown;
+        context?: {
+            goalId: string;
+            goalVersion: number;
+            originRunId?: string;
+            originItemId?: string;
+        };
+        validForMs?: number;
+    }): Promise<{
+        approval: ServerApproval;
+        deduplicated: boolean;
+    }>;
+    /**
+     * What the server says about a pursuit's approvals, right now.
+     *
+     * READ AT DECISION TIME, NEVER KEPT. This is the opposite of `ServerApproval`
+     * above and the reason the two types exist: that one is identity, checked
+     * once at creation and true for ever; this one is state, true only at the
+     * instant it was read. Between one tick and the next a person may approve,
+     * deny or revoke, so an answer to this question is worth exactly one
+     * decision and is never a fact to store.
+     *
+     * NARROWED TO ONE PURSUIT AND ONE VERSION, because that is the only question
+     * a controller has. An approval raised for version 4 was approved for wording
+     * that no longer exists; it cannot be claimed and must not hold version 5.
+     *
+     * `state` here is what the row SAYS, not necessarily what it means: the
+     * server settles expiry when a single approval is read and this route does
+     * not, so a window that closed an hour ago still comes back `requested`.
+     * `deriveApprovalGate` applies the clock. Do not read `state` directly.
+     */
+    projectApprovals(projectId: string, goal: {
+        goalId: string;
+        goalVersion: number;
+    }, limit?: number): Promise<ServerApprovalRow[]>;
+    /**
+     * One approval, as the server holds it now.
+     *
+     * ASKED ONCE, WHEN A RUN IS RESUMING, and never in a loop. Unlike the list
+     * above, reading a single approval SETTLES it: the server closes a window
+     * that has passed before answering, so a person is never shown authority that
+     * has run out. That is exactly what a resuming run wants and exactly what a
+     * polling caller must not do.
+     */
+    projectApproval(projectId: string, approvalId: string): Promise<ServerApprovalRow>;
+    /**
+     * TRANSPORT FOR THE GOVERNED PATH, AND ONLY TRANSPORT.
+     *
+     * Until 7B5 this file was asserted to contain no claim vocabulary at all, and
+     * that assertion was right for a phase where nothing could carry an action
+     * out. What it was really protecting is that a HOLD, a RESUME or a GATE never
+     * goes near a claim — and those files still do not. The guard is re-aimed
+     * rather than dropped, and the list it now covers is the one that matters:
+     * `run-approval`, `round-runner`, `pending-action`, `run-cmd` and every file
+     * on the autonomy path stay claim-free, and the vocabulary lives here and in
+     * the two purpose-built governed modules.
+     *
+     * Nothing below decides anything. Each one composes a URL and parses a reply;
+     * every predicate about whether the thing may happen is the server's.
+     */
+    /**
+     * Take the execution authority an owner granted.
+     *
+     * `claimRef` is derived from the durable Start reservation, never chosen here
+     * and never derived from a run — a recovering process must be able to present
+     * the identical key and reach the server's idempotent arm.
+     */
+    claimApproval(projectId: string, approvalId: string, input: {
+        claimRef: string;
+        expectedFingerprint: string;
+        expectedVersion: number;
+    }): Promise<ServerApprovalRow & {
+        claimId: string | null;
+        version: number;
+    }>;
+    /**
+     * Turn a claim into the one execution it authorises, and be told what to do.
+     *
+     * The reply is the SERVER's envelope. The action inside it is the stored,
+     * re-verified one — this machine sends a digest saying what it believes it is
+     * executing and never an action of its own.
+     */
+    beginExecution(projectId: string, approvalId: string, input: {
+        claimId: string;
+        expectedFingerprint: string;
+    }): Promise<ServerExecutionEnvelope>;
+    /** What came of the attempt. Recorded once, against this exact execution. */
+    settleExecution(projectId: string, executionId: string, input: {
+        claimId: string;
+        expectedVersion: number;
+        expectedFingerprint: string;
+        outcome: 'success' | 'failure' | 'ambiguous';
+        reason?: string;
+        evidence?: Record<string, string | number | boolean>;
+    }): Promise<ServerExecution>;
+    /** Take ownership of delivering a settled result. Exactly one run may. */
+    assignExecutionResult(projectId: string, executionId: string, runId: string): Promise<ServerExecution>;
+    /** Say the result was received. Only the owning run may, and only once. */
+    acknowledgeExecutionResult(projectId: string, executionId: string, runId: string): Promise<ServerExecution>;
+    popCommands(machineId: string): Promise<{
+        commands: ServerCommand[];
+    }>;
+    /**
+     * Report a command finished. `refused` is as final as `done`: it tells the
+     * server this build will never carry the verb out, so it stops being handed
+     * back on every poll.
+     */
+    ackCommand(commandId: string, outcome?: 'done' | 'refused', reason?: string): Promise<{
+        id: string;
+        alreadyAcked: boolean;
+    }>;
+}
+/**
+ * An approval as the server reports it back, narrowed to what a machine may act on.
+ *
+ * FIVE FIELDS AND NO DECISION. The server's own view of an approval carries a
+ * dozen more — the state, the version, who decided it, when the window closes —
+ * and every one of them is a fact that is only true at the instant it was read.
+ * A machine that held them would be a machine that could believe an approval
+ * was still granted after somebody revoked it.
+ *
+ * What is here is the opposite: identity, and the context the row was filed
+ * under. None of it changes for the life of the row, so a machine comparing
+ * these against what it asked for is asking a question that has one answer for
+ * ever — did the server store MY request, or somebody else's?
+ */
+/**
+ * A granted exemption exactly as the server sends it.
+ *
+ * ⚠️ NOT the core `Exemption`. The server records a DECISION — granted or
+ * refused, by whom, until when — and has no `usedInRound`, because a grant is
+ * spent on commit and the commit trailer is the durable record of that. The
+ * mapping into the core model is `run-cmd`'s job, and it is where `usedInRound`
+ * is filled from this machine's own spend store.
+ */
+/**
+ * A grant as the server holds it.
+ *
+ * ⚠️ THE SAME SHAPE AS `SessionControlGrant` IN CORE, MINUS `machineId`,
+ * which the server does not carry: a grant is about a SESSION in a PROJECT, and
+ * which machine asks about it is the asker's question. `controlVerdict` compares
+ * `asking.machineId` against the grant's, so the transport supplies its own —
+ * and supplying it there rather than reading it from the wire is the point: a
+ * machine cannot be told by a server which machine it is.
+ */
+/**
+ * A question as the server holds it.
+ *
+ * ⚠️ `deadline` AND `answeredAt` ARE STRINGS HERE. They are `Date` columns and
+ * the route serialises them; typing them as `Date` would be the class of defect
+ * the three flagship specs exist to catch — a declared shape no real response
+ * ever had.
+ */
+/**
+ * One claim as the server sends it: FLAT, one row per requirement, carrying
+ * the item that made it.
+ *
+ * 🔴 DELIBERATELY NOT `ItemServing` FROM CORE, which groups a whole item's
+ * claims. The two shapes are different on purpose — the wire says what was
+ * stored, row by row, and the fold takes them grouped — and sharing one name
+ * for both would make a regrouping bug look like a type that already agreed.
+ */
+export interface ServingRow {
+    itemId: string;
+    sourceId: string;
+    ordinal: number;
+    row?: number;
+    /** A gate step name, from the machine's own `config.gates`. */
+    provenBy: string;
+}
+export interface ServerQuestion {
+    readonly id: string;
+    readonly projectId: string;
+    readonly runId: string | null;
+    readonly kind: string;
+    readonly text: string;
+    readonly options: readonly string[];
+    readonly default: string;
+    readonly deadline: string;
+    readonly answer: string | null;
+    readonly answeredBy: string | null;
+    readonly answeredAt: string | null;
+}
+export interface ServerSessionGrant {
+    id: string;
+    issuedBy: string;
+    projectId: string;
+    sessionId: string;
+    repositoryId: string;
+    workspace: string;
+    scope: string[];
+    handshakeNonce: string;
+    issuedAt: string;
+    expiresAt: string;
+    state: 'authorized' | 'revoked' | 'expired';
+    generation: number;
+    /** The optimistic-concurrency token; see core's note on why it is on the view. */
+    version: number;
+}
+export interface ServerExemption {
+    id: string;
+    projectId: string;
+    itemId: string;
+    path: string;
+    decision: string;
+    actor: string;
+    reason: string | null;
+    /** ISO. `listGranted` already excludes a null or past expiry. */
+    expiresAt: string | null;
+    at: string;
+}
+export interface ServerApproval {
+    id: string;
+    projectId: string;
+    actionFingerprint: string;
+    goalId: string | null;
+    goalVersion: number | null;
+    originRunId: string | null;
+    originItemId: string | null;
+}
+/**
+ * An approval as the server reports it in a LIST, for one decision.
+ *
+ * Distinct from `ServerApproval` on purpose, and the split is the point.
+ * `ServerApproval` is identity — did the server store MY request — and every
+ * field on it is immutable, so comparing it is a question with one answer for
+ * ever. This is the opposite: it carries what a person has DONE, which is true
+ * only at the instant it was read, and it exists to be consumed by one
+ * decision and then dropped.
+ *
+ * `state` is a plain string rather than the union, because the server may know
+ * a word this build does not — and `deriveApprovalGate` refuses an unfamiliar
+ * one rather than a parser silently widening it.
+ */
+export interface ServerApprovalRow {
+    id: string;
+    projectId: string;
+    state: string;
+    /** ISO. When the window closes, as the SERVER stamped it. */
+    expiresAt: string;
+    goalId: string | null;
+    goalVersion: number | null;
+    originRunId: string | null;
+    actionType: string;
+    actionFingerprint: string;
+    /**
+     * One line a person could be shown, from 7B1's own formatter.
+     *
+     * The ONE description authority. A resumed run tells its model what was
+     * refused using this string and never a second wording of its own, so what
+     * the model is told and what the person was shown cannot drift.
+     */
+    display: string;
+    /** The owner's own words about their decision. Never authority. */
+    decisionNote: string | null;
+    /**
+     * The row's OCC token, required to claim it.
+     *
+     * On the LIST as well as the detail, because the gate reads the list and a
+     * governed Start has to claim what the gate found without a second round trip
+     * that could see a different row.
+     */
+    version: number;
+    /** Set once execution authority has been taken. Never a result. */
+    claimId: string | null;
+    /**
+     * The one attempt made under this approval's claim, if any.
+     *
+     * Present on the list so the gate can tell `claimed with nothing attempted`
+     * from `carrying out` from `settled and undelivered` in one read. Narrow on
+     * purpose: no evidence, no reason, nothing a caller could branch on beyond
+     * what the gate needs.
+     */
+    execution: {
+        state: string;
+        resultAssignedRunId: string | null;
+        acknowledged: boolean;
+        /**
+         * Whether a PERSON settled what the machine could not. Optional because an
+         * older server does not send it, and `executionOf` reads its absence as
+         * `false` — the safe direction, since reading silence as `true` would free
+         * a pursuit nobody has dealt with.
+         */
+        resolved?: boolean;
+    } | null;
+}
+/**
+ * WHAT THE SERVER SAYS AN EXECUTION IS.
+ *
+ * Distinct from the envelope below in the same way `ServerApprovalRow` is
+ * distinct from `ServerApproval`: this is state, true only at the instant it
+ * was read.
+ */
+export interface ServerExecution {
+    id: string;
+    projectId: string;
+    approvalId: string;
+    claimId: string;
+    machineId: string;
+    actionFingerprint: string;
+    state: string;
+    version: number;
+    startedAt: string;
+    settledAt: string | null;
+    outcomeReason: string | null;
+    evidence: unknown;
+    resultAssignedRunId: string | null;
+    resultAcknowledgedAt: string | null;
+}
+/**
+ * THE ONE THING A BROKER MAY ACT ON, BUILT BY THE SERVER.
+ *
+ * `actionRequest` is the stored canonical payload, re-parsed and re-verified
+ * against the fingerprint a person approved. This machine never assembles one:
+ * it sends a digest saying what it believes it is executing and is told what is
+ * actually held.
+ */
+export interface ServerExecutionEnvelope {
+    executionId: string;
+    approvalId: string;
+    claimId: string;
+    projectId: string;
+    machineId: string;
+    actionFingerprint: string;
+    actionRequest: unknown;
+    actionType: string;
+    display: string;
+    executionVersion: number;
+    executionState: string;
+}
+/**
+ * One act of permission, as the server reports it.
+ *
+ * `state` is a closed union on the wire. A value this build does not know is
+ * reported by the SERVER as `human_required` rather than passed through, so a
+ * machine never has to guess what an unfamiliar ending meant.
+ */
+export interface ServerAutonomy {
+    controllerId: string;
+    goalId: string;
+    goalVersion: number;
+    /** Which act of permission this was within the version. Newest first. */
+    generation: number;
+    state: GoalAutonomyState;
+    reason: string | null;
+    maxStarts: number;
+    expiresAt: string;
+    /** OCC token. Required by `settleGoalAutonomy`, and not optional there. */
+    version: number;
+    createdBy: string;
+    createdAt: string;
+}
+export type ServerCommandKind = 'pause' | 'resume' | 'stop' | 'skip' | 'scan' | 'start-run' | 'approve' | 'undo' | 'release-goal-items'
+/** One person's explicit, bounded permission to keep going. NOT a start-run. */
+ | 'authorize-goal-autonomy';
+export interface ServerCommand {
+    id: string;
+    projectId: string;
+    kind: ServerCommandKind;
+    payload?: unknown;
+    actor: string;
+}
+//# sourceMappingURL=server-client.d.ts.map