halfcycle 0.3.7

package/dist/mcp-endpoint.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ONE HOME for the composition `MCP origin → MCP endpoint URL` (T-24, #446).
+ *
+ * The control plane reports an ORIGIN (`mcpUrl` on the create-engagement 201,
+ * persisted as `HALFCYCLE_MCP_URL`); the method-delivery service serves MCP at
+ * `/mcp` on it. Two callers need the composed endpoint and they must not disagree:
+ *
+ *   - `install.ts`  — writes it into `.mcp.json` as a LITERAL url (T-24).
+ *   - `probe-mcp.ts` — calls it at install time to say whether that origin answers.
+ *
+ * Until T-24 the registration carried `${HALFCYCLE_MCP_URL}/mcp` — a template the
+ * client expanded — so `probe-mcp.ts` held the only executable copy of this rule
+ * and `install.ts` held a textual one. Now that the installer writes the composed
+ * address itself, both copies would be real, and a probe that appended `/mcp`
+ * while the registration appended something else would report an origin reachable
+ * and still install a registration that reaches nothing. That is the two-homes
+ * failure `create-engagement.ts` already names in prose ("the one place that
+ * composes the MCP URL"); this module is that one place.
+ *
+ * INV-001: no imports at all — not even Node builtins.
+ */
+/** The path the method-delivery service serves MCP on. Stated once. */
+export declare const MCP_ENDPOINT_PATH = "/mcp";
+/**
+ * Compose the MCP endpoint URL for an origin.
+ *
+ * Trailing slashes on the origin are stripped, so an origin reported as
+ * `https://host/` cannot compose `https://host//mcp`. `createEngagement` already
+ * normalises what it returns, but `install()` is also called programmatically, so
+ * the normalisation lives with the composition rather than only at the boundary.
+ *
+ * @param origin  The MCP origin (no path), e.g. `https://halfcycle-delivery.fly.dev`.
+ */
+export declare function mcpEndpointUrl(origin: string): string;
+//# sourceMappingURL=mcp-endpoint.d.ts.map

package/dist/mcp-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-endpoint.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/merge-settings.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Settings merge — the one function whose bug destroys client work.
+ *
+ * `.claude/settings.json` is MERGED, never replaced (operator decision (aq)).
+ * Every key the developer has is kept at its existing value, `$schema` excepted.
+ * Halfcycle's three hook entries are appended beside the developer's — possible
+ * without conflict because Claude Code runs every hook registered for an event.
+ *
+ * The merge is UPSERT-BY-IDENTITY, not append: a Halfcycle-authored entry already
+ * present is replaced in place, so a second install does not fire the guard twice
+ * per edit. Identity is decided by the hook command string, which is the stable,
+ * generated marker of a Halfcycle-authored entry (each of our three commands is a
+ * distinct `bash ./.claude/hooks/...` invocation).
+ *
+ * See docs/features/client-install-surface.md, criterion 4.
+ * INV-001: this file imports only Node builtins (none needed).
+ */
+/** A single hook command as Claude Code's settings schema records it. */
+export interface HookCommand {
+    type?: string;
+    command: string;
+    timeout?: number;
+}
+/** A matcher-scoped group of hook commands for one event. */
+export interface HookEntry {
+    matcher?: string;
+    hooks: HookCommand[];
+}
+/**
+ * The permission rules Claude Code evaluates, deny → ask → allow, first match
+ * wins. Only `deny` is ever generated by Halfcycle (F-23 decision (b)); the other
+ * two appear here because a developer may own them and they must survive.
+ */
+export interface ClaudePermissions {
+    deny?: string[];
+    allow?: string[];
+    ask?: string[];
+    [key: string]: unknown;
+}
+/** The subset of `.claude/settings.json` this merge reasons about. */
+export interface ClaudeSettings {
+    $schema?: string;
+    hooks?: Record<string, HookEntry[]>;
+    permissions?: ClaudePermissions;
+    [key: string]: unknown;
+}
+/**
+ * Merge Halfcycle's generated hook entries into an existing settings object.
+ *
+ * @param existing  the developer's parsed `.claude/settings.json` (may be `{}`).
+ * @param generated Halfcycle's fresh settings object (from `generateSettingsJson`).
+ * @returns a new settings object: every developer key preserved, `$schema` taken
+ *          from `generated`, and for each event Halfcycle's entries upserted
+ *          beside the developer's — exactly one Halfcycle entry per event.
+ */
+export declare function mergeSettings(existing: ClaudeSettings, generated: ClaudeSettings): ClaudeSettings;
+//# sourceMappingURL=merge-settings.d.ts.map

package/dist/merge-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-settings.d.ts","sourceRoot":"","sources":["../src/merge-settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAYD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,GAAG,cAAc,CAwCjG"}

package/dist/mint-board-code.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Mint the board's first-visit code — the installer's second HTTP call (T-19,
+ * #363; `client-mission-control` criterion 4, step 2).
+ *
+ * `POST {baseUrl}/board/enter-codes` with the engagement's own credential as a
+ * bearer and an empty body: the engagement is resolved from the credential and
+ * never read from the body. The control plane answers
+ * `{ enterCode, engagementId, boardUrl, expiresAt }`. The installer prints the
+ * address and the code; the developer pastes the code once, in a browser.
+ *
+ * The installer is the ONE minting site this phase builds. A standing re-mint
+ * command belongs to the installer spec's second-run work; until it exists, an
+ * expired or spent code is recovered by re-running the installer — which the
+ * printed lines say rather than leave to be discovered.
+ *
+ * INV-001: this file imports only the global `fetch` (Node 20). It never imports
+ * the control service — the mint is an external HTTP contract, exactly as
+ * `create-engagement.ts` treats `POST /engagements`.
+ */
+/** What `POST /board/enter-codes` returns on 201. */
+export interface MintedBoardCode {
+    /** The single-use plaintext, printed once and never stored by the installer. */
+    enterCode: string;
+    engagementId: string;
+    /** The first-visit address — a plain URL carrying no credential. */
+    boardUrl: string;
+    /** UTC ISO-8601 absolute expiry. */
+    expiresAt: string;
+}
+/**
+ * Mint a first-visit board code for the engagement the credential resolves to.
+ *
+ * @param baseUrl       The platform origin (`HALFCYCLE_SERVICE_URL`).
+ * @param sessionToken  The engagement's own credential, as a bearer.
+ * @throws              on transport failure, a non-2xx status, or a body missing
+ *                      any of the four fields. The caller decides what a failure
+ *                      means; for the installer it means printing a recoverable
+ *                      note, never failing an install that already succeeded.
+ */
+export declare function mintBoardEnterCode(baseUrl: string, sessionToken: string): Promise<MintedBoardCode>;
+//# sourceMappingURL=mint-board-code.d.ts.map

package/dist/mint-board-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mint-board-code.d.ts","sourceRoot":"","sources":["../src/mint-board-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,CAAC,CAwC1B"}

package/dist/open-phase.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Open-phase wiring — the CLI's call to `POST {baseUrl}/engagements/:id/phase`
+ * (FX-11, operator decision D-2).
+ *
+ * `openPhase` has had a real entry gate since FW-7 — it refuses an unmet entry
+ * condition, demands an explicit override, and records who crossed what — and no
+ * surface at all, so the only way anyone has ever opened a phase is a scratch script
+ * that ran inside the control plane. This module is the CLIENT half of the answer:
+ * the developer whose repo the phase belongs to can open it from their own repo,
+ * through the gate, with their own credential.
+ *
+ * WIRING, NOT MACHINERY. Every rule lives on the control plane: what makes a decision
+ * substantive, what the store can evaluate for itself, what an override crosses. This
+ * module builds the request, sends it, and reports what came back — including the
+ * refusal, in the plane's own words. It re-checks nothing, because a second copy of
+ * the entry rule in a shippable package is a copy that can disagree with the one that
+ * decides.
+ *
+ * INV-001: this file imports the global `fetch` (Node 20), Node builtins, and
+ * `@halfcycle/events` — one of the exactly two workspace packages a shippable may
+ * import. `phaseEntryDecisionSchema` is the ONE home for the decision's shape
+ * (INV-003), so the CLI validates what it builds against the same schema the route
+ * parses with rather than a second hand-written copy. It never imports the control
+ * service; the route is an external HTTP contract, exactly as `createEngagement` and
+ * `mintBoardEnterCode` treat theirs.
+ */
+import { type PhaseEntryDecision } from '@halfcycle/events';
+/** What `POST /engagements/:id/phase` returns on 200 (the fields the CLI reports). */
+export interface OpenedPhase {
+    /** What is open now. `null` is project scope. */
+    phase: string | null;
+    /** What was open before. `null` is project scope. */
+    previousPhase: string | null;
+    decision: {
+        decisionId: string;
+        decision: string;
+        actor: string;
+        justification: string;
+        /** The finding this decision crossed, or `null` when it crossed none. */
+        blockingFinding: string | null;
+        decidedAt: string;
+    };
+}
+/**
+ * A refusal from the control plane, carried as an error the CLI can print whole.
+ *
+ * The `finding` is the point. A `409` here means the phase the engagement is in was
+ * never accepted, and the plane says WHICH phase and WHY — the developer needs that
+ * sentence, not a status code. It rides its own field so the CLI never parses prose.
+ */
+export declare class OpenPhaseRefused extends Error {
+    readonly status: number;
+    readonly finding: string | null;
+    constructor(status: number, message: string, finding: string | null);
+}
+/**
+ * The three credential keys this call needs. They are the installer's own keys —
+ * `install.ts` writes them and `.mcp.json`/the guard hook read them — and this list
+ * is deliberately a SUBSET of that write set, asserted as one in the tests rather
+ * than left to two lists agreeing by eye.
+ */
+export declare const OPEN_PHASE_ENV_KEYS: readonly ["HALFCYCLE_SERVICE_URL", "HALFCYCLE_TOKEN", "HALFCYCLE_ENGAGEMENT_ID"];
+export interface RepoCredential {
+    serviceUrl: string;
+    token: string;
+    engagementId: string;
+}
+/**
+ * Read the credential for the engagement this repository is installed against.
+ *
+ * **WHERE IT LOOKS CHANGED AT T-09, AND THE REPO ROOT IS STILL THE ARGUMENT.** The
+ * credential used to sit in the tree at `.env.local`. It now lives at machine level
+ * (`engagement-credential.ts`), keyed on the engagement — so the repo root is what
+ * names the engagement (via the committed `.halfcycle/bundle.json` pin) rather than
+ * what holds the secret. The parameter kept its meaning: *the repository whose
+ * engagement this is*.
+ *
+ * READ, NEVER SOURCED — a credential store is not code, and this parses `KEY=value`
+ * lines exactly as the generated `mcp-headers.sh` does. The process environment WINS
+ * when it carries a key, so an operator can point one command at a different plane
+ * without editing a file, and a CI job with no per-user store works by exporting
+ * them.
+ *
+ * Why any file is read at all: nothing loads a credential into a shell. A verb that
+ * only read `process.env` would work for whoever had already exported three
+ * variables and fail, confusingly, for the developer whose install wrote them thirty
+ * seconds earlier.
+ *
+ * @throws with the missing key NAMED, and the file it was looked for in. "Not
+ *         configured" is the one message a developer cannot act on.
+ */
+export declare function readRepoCredential(repoRoot: string, env?: NodeJS.ProcessEnv, home?: string): RepoCredential;
+/**
+ * Open a phase on the engagement (or, with `phase: null`, return it to project
+ * scope).
+ *
+ * The decision is a REQUIRED parameter, mirroring `openPhase`'s own signature and the
+ * wire schema's required `entry`: there is no argument-less form here either, at any
+ * layer, by construction rather than by review.
+ *
+ * @throws OpenPhaseRefused on a 4xx the plane explained (an unmet entry condition, a
+ *         decision that says nothing, a bad credential), so the CLI prints the
+ *         plane's own sentence and exits non-zero.
+ * @throws Error on transport failure or a body that is not the expected shape.
+ */
+export declare function openPhase(credential: RepoCredential, phase: string | null, entry: PhaseEntryDecision): Promise<OpenedPhase>;
+//# sourceMappingURL=open-phase.d.ts.map

package/dist/open-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-phase.d.ts","sourceRoot":"","sources":["../src/open-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAOtF,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qDAAqD;IACrD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE;QACR,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,yEAAyE;QACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,MAAM,EAAE,MAAM;aAEd,OAAO,EAAE,MAAM,GAAG,IAAI;gBAFtB,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,GAAG,IAAI;CAKzC;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,kFAItB,CAAC;AAEX,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CA0BhB;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,WAAW,CAAC,CA0DtB"}

package/dist/probe-mcp.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reach the MCP origin the platform reported, so the installer can say WHICH of
+ * the two origins is wrong (T-22, #438 — `client-install-surface` criterion 5).
+ *
+ * **The failure this exists to make legible.** The install writes two addresses:
+ * `HALFCYCLE_SERVICE_URL` (the control plane, which the developer configures) and
+ * `HALFCYCLE_MCP_URL` (the method-delivery service, which the platform reports).
+ * A bad control origin already fails loudly, at the create call. A bad MCP origin
+ * failed SILENTLY: the install completed, the tree was correct, `.mcp.json` named
+ * an address, and the developer found out when `/halfcycle-setup` did nothing in
+ * their editor — a 404 with no clue which half of a two-service platform was
+ * wrong. This turns that into one sentence at install time.
+ *
+ * **It never fails the install.** The tree is already correct and the credential
+ * is already written; refusing an install over a service that may simply be
+ * restarting would be worse than saying so. Same degrade posture as the board
+ * mint in `bin.ts`.
+ *
+ * **`initialize` is the probe** because it is the one MCP call that needs no
+ * credential and identifies the server: a wrong origin 404s, a right one answers
+ * with its `serverInfo`. The alternative — a plain `GET /health` — would prove an
+ * origin is alive without proving it serves MCP, which is exactly the distinction
+ * that was missing.
+ *
+ * INV-001: Node builtins and the global `fetch` only. No hosted import.
+ */
+export type McpProbe = 
+/** `POST {origin}/mcp` answered as an MCP server. `serverName` is what it called itself. */
+{
+    reached: true;
+    serverName: string;
+}
+/** It did not. `problem` is a plain-words sentence naming what happened. */
+ | {
+    reached: false;
+    problem: string;
+};
+/**
+ * Ask the MCP origin to identify itself.
+ *
+ * @param mcpUrl  The ORIGIN (no path) the create response reported. The endpoint
+ *                is composed by `mcpEndpointUrl` — the SAME function that composes
+ *                the literal url written into `.mcp.json` (T-24), so this probe
+ *                cannot report an address the registration does not use.
+ */
+export declare function probeMcpOrigin(mcpUrl: string): Promise<McpProbe>;
+//# sourceMappingURL=probe-mcp.d.ts.map

package/dist/probe-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-mcp.d.ts","sourceRoot":"","sources":["../src/probe-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,MAAM,MAAM,QAAQ;AAClB,4FAA4F;AAC1F;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE;AACvC,4EAA4E;GAC1E;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuCtE"}

package/dist/resolve-credential.d.ts

@@ -0,0 +1,126 @@
+/**
+ * THE CREDENTIAL RESOLVER — environment variable → per-user store → browser
+ * handoff (T-08, feature `connect-signup-and-credential`).
+ *
+ * One home for the question *"what credential does this run present to control, and
+ * where did it come from?"*. `bin.ts` asks it once, before anything is written.
+ *
+ * ---------------------------------------------------------------------------
+ * THE ORDER IS AN ACCEPTANCE CRITERION, NOT A CONVENIENCE. *"CI works with no
+ * browser and no per-user store: `HALFCYCLE_TOKEN` in the environment is accepted
+ * and TAKES PRECEDENCE over the stored credential."* A workflow that exports a
+ * credential has said which identity this run is, and a stored credential left
+ * behind on a shared or long-lived runner must not silently win over it — the
+ * symptom of that inversion is a job that quietly does its work as the wrong
+ * account, which nothing about the run's output would reveal.
+ *
+ * The environment arm also DOES NOT TOUCH THE STORE AT ALL: it neither reads it nor
+ * writes it. A CI job must not leave a credential behind on a runner's home
+ * directory, and a developer who exports the variable for one command must not find
+ * their saved sign-in replaced by it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THE SOURCE IS RETURNED AND NOT JUST THE SECRET. When control refuses a
+ * credential, the remedy depends entirely on where it came from: a stored one is
+ * replaced by signing in again (which this CLI can just do), an environment one
+ * cannot be — the variable still takes precedence, so "run it again" would loop
+ * forever presenting the same dead value. That is the *remedy naming something the
+ * reader cannot act on* defect (`docs/topology-boundary.md` rule 2), and returning
+ * the source is what lets the refusal path avoid it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT "REFRESH" MEANS HERE, because the client half of it is smaller than it
+ * sounds and the difference matters. The 30-day window is refreshed SERVER-SIDE, on
+ * every successful use: `resolveAccountCredential` extends `expires_at` in the same
+ * statement that validates the credential, and it is the one home of that number. No
+ * response tells this client the extended value, so there is nothing to write back
+ * and nothing to re-time locally — using the credential IS the refresh. The client
+ * half is therefore exactly two things: keep presenting the stored credential, and
+ * when control finally refuses one, treat that as *sign in again* rather than as
+ * something to retry. Anything more — a locally-tracked expiry, a client-side TTL, a
+ * pre-emptive rotate call — would be a second home for a lifetime the operator set
+ * in one place, and there is no client-reachable rotate route to call anyway
+ * (`rotateToken`'s only non-test caller is an operator script).
+ *
+ * INV-001: Node builtins, `@halfcycle/events` (transitively, via `device-signin`),
+ * and bundle-internal modules.
+ */
+import { type SignInDeps } from './device-signin.js';
+/** Where the credential this run presents came from. */
+export type CredentialSource = 
+/** `HALFCYCLE_TOKEN` in the process environment — the CI path, and it wins. */
+'environment'
+/** `~/.halfcycle/account.json` — this machine has signed in before. */
+ | 'stored'
+/** The browser handoff just ran, and the result has been stored. */
+ | 'browser-handoff';
+export interface ResolvedCredential {
+    credential: string;
+    source: CredentialSource;
+    /**
+     * The account the credential speaks for, when it is known. ABSENT for the
+     * environment arm — a bare variable carries no identity and this CLI does not go
+     * and ask, because the only way to find out is to spend a call, and control will
+     * tell us by accepting or refusing it a moment later anyway.
+     */
+    accountId?: string;
+}
+export interface ResolveOptions extends SignInDeps {
+    /** The process environment to read `HALFCYCLE_TOKEN` and `CI` from. */
+    env?: NodeJS.ProcessEnv;
+    /** The home directory the per-user store lives under. Defaults to `os.homedir()`. */
+    home?: string;
+}
+/**
+ * Resolve a credential for `serviceUrl`, signing in through the browser if this
+ * machine has none.
+ *
+ * A successful handoff is STORED before this returns, so the next run skips it —
+ * that is what makes *"an already-signed-in machine skips all of it"* true. It is
+ * stored BEFORE the credential is used for anything, deliberately: a credential
+ * obtained and then lost because the create call failed would send the developer
+ * back through the browser for a reason that had nothing to do with signing in.
+ */
+export declare function obtainCredential(serviceUrl: string, opts?: ResolveOptions): Promise<ResolvedCredential>;
+/**
+ * Control refused the credential we presented. Replace it, if replacing it is a
+ * thing this CLI is allowed to do.
+ *
+ * Returns the new credential, or `null` when there is nothing to replace — in which
+ * case the caller must print the refusal and exit non-zero rather than retry.
+ *
+ * THE THREE ARMS, and why only one of them re-signs-in:
+ *
+ *   `environment`     → null. The variable takes precedence over anything this
+ *                       function could store, so signing in again would produce a
+ *                       credential the very next resolve would ignore. The operator
+ *                       who set the variable is the only one who can fix it.
+ *   `stored`          → forget it and sign in again. There is no grace window on
+ *                       this credential class and nothing rotates it, so a refusal
+ *                       is terminal for that value: keeping it would mean every
+ *                       later run presenting something that can only fail. This is
+ *                       the 30-day window closing on a machine that sat idle — the
+ *                       *"sends the developer back through the browser once"* half
+ *                       of operator decision 4.
+ *   `browser-handoff` → null. The credential was minted seconds ago and control has
+ *                       already refused it; signing in again would mint another one
+ *                       from the same route and hand back the same refusal, one
+ *                       browser round-trip later. A loop that ends where it started
+ *                       is worse than a message, so this reports rather than retries.
+ */
+export declare function replaceRefusedCredential(serviceUrl: string, refused: ResolvedCredential, opts?: ResolveOptions): Promise<ResolvedCredential | null>;
+/**
+ * The sentence for a refusal this CLI cannot recover from, chosen by where the
+ * credential came from.
+ *
+ * ONE HOME for that selection, and it exists because the alternative already shipped
+ * once in this repository: a single remedy written for all three situations, printed
+ * to whoever hit any of them. `bin.ts` already selects its guard-off remedy this way
+ * for the same reason (walk 9 `F-2` — a line that told a developer to set a variable
+ * that was already set, on the invocation that printed it).
+ *
+ * The `message` control sent is carried through in every arm, because control's
+ * refusal is the fact and this is the local advice on top of it.
+ */
+export declare function refusedCredentialRemedy(source: CredentialSource): string;
+//# sourceMappingURL=resolve-credential.d.ts.map

package/dist/resolve-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-credential.d.ts","sourceRoot":"","sources":["../src/resolve-credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAOH,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE7D,wDAAwD;AACxD,MAAM,MAAM,gBAAgB;AAC1B,+EAA+E;AAC7E,aAAa;AACf,uEAAuE;GACrE,QAAQ;AACV,oEAAoE;GAClE,iBAAiB,CAAC;AAEtB,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CA0B7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,EAC3B,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAmBpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAqBxE"}

package/dist/scan.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The bootstrap scan — INV-021's one permitted repository read.
+ *
+ * Writes `.halfcycle/state.json`, a client-side, gitignored cache of DERIVED
+ * position. It is not a state record and it is not a record store: the
+ * authoritative position is computed entirely hosted-side, in-process, from
+ * the one satisfaction oracle over the state-record table. This module holds
+ * no database client, no store handle and no import path to any hosted
+ * package, so it cannot reach that oracle — see the import-boundary test,
+ * `packages/bundle/test/scan-import-boundary.test.ts`.
+ *
+ * What it may write, and the whole of what it may write (INV-021):
+ *   - a **second-class** value, `'asserted'`, set per LAYER (never per step) when
+ *     the repository already holds that layer's artefact(s) on disk;
+ *   - never `'green'`; never anything that satisfies a `requires` edge or counts
+ *     toward a gate — those are hosted-side concepts this file never touches;
+ *   - carrying its own provenance (`source: 'bootstrap-scan'`, the paths found,
+ *     and when the scan ran) so a reader can never mistake it for a record —
+ *     PLUS a file-level `note` saying the same of the file as a whole, because
+ *     an EMPTY `layers` has no entry to carry provenance, and emptiness is
+ *     exactly the case that misled a cold session (W3-F-1, walk 4);
+ *   - superseded by the first REAL record for that layer — this module has no
+ *     opinion on that; a caller merges/overlays hosted records over this file's
+ *     `asserted` rows and MUST prefer the real record. See `mergeWithRecords`.
+ *
+ * Runs ONCE, during onboarding, and never again (INV-021's reworded clause —
+ * decision (bb) names no command). `runBootstrapScan` is idempotent-refusing:
+ * it does nothing if `.halfcycle/state.json` already exists, so re-running the
+ * installer or resolving `/halfcycle-setup` a second time cannot re-scan.
+ *
+ * INV-001: this file imports only @halfcycle/events and Node builtins.
+ */
+import { methodLayerSchema, type MethodLayer } from '@halfcycle/events';
+/** The state file's format tag — bumped only on a breaking shape change. */
+export declare const HALFCYCLE_STATE_FORMAT: "halfcycle-state-file/v1";
+/** Re-exported so a consumer can validate a layer key without a second import. */
+export { methodLayerSchema };
+/**
+ * The only non-absent value this module ever writes — there is no
+ * `'green'`/`'complete'` member because INV-021 forbids this file from ever
+ * claiming one. A layer with no matching artefact on disk simply has no
+ * entry (absence, not a `'not-instrumented'` literal — that rendering is the
+ * hosted board's, per `state-contract.md` Non-goals, and this file does not
+ * reproduce it).
+ */
+export type ScannedLayerValue = 'asserted';
+/** One layer's scanned entry, with its own provenance. */
+export interface ScannedLayerEntry {
+    value: ScannedLayerValue;
+    /** Always 'bootstrap-scan' — the one emitter this file ever has. */
+    source: 'bootstrap-scan';
+    /** Repo-relative paths whose presence caused this layer to be asserted. */
+    foundPaths: string[];
+    /** When the (one, onboarding-time) scan ran. */
+    scannedAt: string;
+}
+/**
+ * What the file says about itself, in the file, for a reader who has only the
+ * file (W3-F-1). Every per-layer entry already carries provenance so it "can
+ * never be mistaken for a record" — but an EMPTY `layers` has no entry to carry
+ * it, and emptiness is the state a greenfield install writes and then keeps for
+ * the life of the engagement. Walk 4's cold session read `{"layers":{}}`,
+ * concluded "literally nothing recorded", and told the developer to redo an
+ * approval gate they had already passed. The provenance rule was sound; it just
+ * had nowhere to live in the one case that misleads.
+ *
+ * This is deliberately prose rather than a flag: the reader that gets this
+ * wrong is a language model reading JSON it did not expect, and a `false` on a
+ * key it has never seen carries no instruction. Kept to one sentence per claim.
+ */
+export declare const HALFCYCLE_STATE_NOTE: string;
+/** The whole of `.halfcycle/state.json`. */
+export interface HalfcycleStateFile {
+    format: typeof HALFCYCLE_STATE_FORMAT;
+    /**
+     * Self-description, always written, always the same string. Present so that
+     * an empty `layers` still tells a reader what it is and where to ask instead.
+     */
+    note: typeof HALFCYCLE_STATE_NOTE;
+    /** Per-layer scan results. Only layers with a hit are present. */
+    layers: Partial<Record<MethodLayer, ScannedLayerEntry>>;
+}
+/**
+ * The repo-relative artefact paths that, if present, assert a layer. Kept
+ * narrow and file-existence-only — this is a presence check, not a content
+ * judgement, and it never reads a record store (there is none to read from a
+ * client machine; see the module docblock).
+ *
+ * Layers with no local artefact convention (`l3-l4`, `xl`) are deliberately
+ * absent — the scan has nothing on disk to look for and asserts nothing.
+ *
+ * **Exported so there is ONE home for it.** The discover phase
+ * (`src/setup/discovery.ts`) needs the same "which document belongs to which
+ * layer" table to report which layer documents already exist, and a second copy
+ * there would drift the moment either moved. It consumes the CONSTANT and never
+ * `scanLayers`, so no second position value is constructed: discovery reports a
+ * file's existence with its path as the anchor, and derives no `asserted`
+ * (INV-021 — position is computed from records, and the one permitted scan is
+ * this module's).
+ */
+export declare const LAYER_ARTEFACT_PATHS: Partial<Record<MethodLayer, string[]>>;
+/** Scan `targetRepo` for each layer's artefact convention. Pure filesystem read. */
+export declare function scanLayers(targetRepo: string, scannedAt?: string): HalfcycleStateFile;
+/**
+ * Run the bootstrap scan ONCE. If `.halfcycle/state.json` already exists this
+ * is a no-op (returns the existing file unchanged) — the "never again" half of
+ * INV-021's onboarding clause, enforced here rather than left to caller
+ * discipline. Returns the file that is now on disk either way.
+ */
+export declare function runBootstrapScan(targetRepo: string): {
+    state: HalfcycleStateFile;
+    ran: boolean;
+};
+/**
+ * What a layer reads as, once real records are known. This is the reader's
+ * side of the "superseded by the first real record" rule — it takes the local
+ * scan file and a set of layers the HOSTED oracle already holds a satisfying
+ * record for (computed elsewhere, over HTTP, never read from disk here), and
+ * returns a merged view where any layer with a real record reads `'complete'`
+ * regardless of what the scan asserted, and every other layer reads the scan's
+ * `'asserted'` or is absent.
+ *
+ * This function takes the real-record set as a plain `Set<MethodLayer>`
+ * parameter — never a store handle, a pool, a URL, or anything else that could
+ * let a caller wire this file to a live query. That is the structural half of
+ * criterion 3: nothing in `packages/bundle` can reach the hosted oracle, so the
+ * only way "real records" enter this function is a value the CALLER already
+ * computed and handed in.
+ */
+export declare function mergeWithRecords(state: HalfcycleStateFile, layersWithRealRecords: ReadonlySet<MethodLayer>): Partial<Record<MethodLayer, 'asserted' | 'complete'>>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMxE,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,EAAG,yBAAkC,CAAC;AAEzE,kFAAkF;AAClF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAE3C,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,iBAAiB,CAAC;IACzB,oEAAoE;IACpE,MAAM,EAAE,gBAAgB,CAAC;IACzB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,QAStB,CAAC;AAEZ,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC;;;OAGG;IACH,IAAI,EAAE,OAAO,oBAAoB,CAAC;IAClC,kEAAkE;IAClE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;CACzD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,CAOvE,CAAC;AAMF,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,GAAE,MAAiC,GAAG,kBAAkB,CAc/G;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,OAAO,CAAA;CAAE,CAUhG;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,kBAAkB,EACzB,qBAAqB,EAAE,WAAW,CAAC,WAAW,CAAC,GAC9C,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,GAAG,UAAU,CAAC,CAAC,CAcvD"}

package/dist/setup/discovery.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The discover phase — everything discoverable is discovered before anything is
+ * asked, and every discovered value carries an anchor (feature `halfcycle-setup`,
+ * criterion 1; task T-17).
+ *
+ * **The rule this module exists to make unbreakable.** A discovered value with no
+ * `file:line` or command output is NOT discovered — it is an assumption, and it
+ * moves into the confirm phase as a decision rather than being presented as a
+ * finding. That is what stops the discover phase becoming a plausible guess the
+ * developer is invited to rubber-stamp. It is enforced by construction here: a
+ * finding cannot be built without an anchor, and the one function that takes a
+ * possibly-anchorless value returns a QUESTION when the anchor is missing.
+ *
+ * **What it reads and what it does not.** Plain filesystem reads of the project's
+ * own files. It computes no position, writes nothing, and constructs no `asserted`
+ * value — the one permitted position-setting read of the repository is the
+ * bootstrap scan's (`src/scan.ts`, INV-021), and this module borrows only its
+ * layer→document table so there is one home for it.
+ *
+ * INV-001: Node builtins and `./scan.js` (same package) only.
+ */
+/** Where a discovered value came from. There is no third form: if neither a file
+ *  line nor a command's output can be pointed at, the value is not a finding. */
+export type FactAnchor = {
+    readonly kind: 'file';
+    readonly path: string;
+    readonly line: number;
+} | {
+    readonly kind: 'command';
+    readonly command: string;
+    readonly output: string;
+};
+/** One thing the repository answered, and where it said so. */
+export interface DiscoveredFact {
+    /** A stable key so the confirm phase can tell which questions are already answered. */
+    readonly key: string;
+    /** What the developer is told, in their language. */
+    readonly value: string;
+    readonly anchor: FactAnchor;
+}
+/** One thing the repository could not answer, so it is asked. */
+export interface OpenQuestion {
+    readonly key: string;
+    /** The question, in plain words. */
+    readonly question: string;
+    /** Why it is being asked rather than reported — always the same shape: nothing
+     *  in the repository anchors an answer. */
+    readonly why: string;
+}
+export interface DiscoveryResult {
+    readonly findings: readonly DiscoveredFact[];
+    readonly questions: readonly OpenQuestion[];
+}
+/** Render one anchor the way the discover phase prints it: every line carries the
+ *  file or command it came from. */
+export declare function renderAnchor(anchor: FactAnchor): string;
+/**
+ * Read a project repository and report what it answers, each line carrying the file
+ * it came from — and what it does not answer, as questions for the confirm phase.
+ *
+ * Nothing is asked here and nothing is written. The caller puts the questions.
+ */
+export declare function discoverRepository(targetRepo: string): DiscoveryResult;
+/**
+ * The question set the confirm phase actually puts: every question discovery could
+ * not settle. A key that appears as a finding never appears here — that is the
+ * "omits every fact those files answer" property, stated as one function so a
+ * caller cannot re-derive it differently.
+ */
+export declare function questionsToPut(result: DiscoveryResult): readonly OpenQuestion[];
+/** The discover phase's report: one line per finding, each carrying its anchor. */
+export declare function renderDiscovery(result: DiscoveryResult): string;
+//# sourceMappingURL=discovery.d.ts.map