halfcycle 0.3.7

package/dist/cli-contract.d.ts

@@ -0,0 +1,120 @@
+/**
+ * What each `halfcycle` verb REQUIRES — declared once, enforced from the
+ * declaration (walk 8 `F-5`, W8-T-02).
+ *
+ * ---
+ *
+ * **Why this file exists.** `orchestrator.ts` in the control plane printed
+ * `halfcycle close-phase <phase> --verdict <clean|defects>` as the remedy for a
+ * refusal. Wave 7 made `--actor` mandatory on that verb and did not update the
+ * sentence, so the product's own printed instruction exited 2 when a developer ran
+ * it. That is walk 6's `F-1` class — a remedy is a claim about a command, and a
+ * claim goes stale silently — recurring in the wave that had been warned about it.
+ *
+ * The fix for one string is one string. The fix for the CLASS is that the
+ * requirement stops living in `bin.ts`'s argument handling as a sequence of ad-hoc
+ * `if (!flag)` checks that nothing else can read. Here it is DATA: the verb, the
+ * flags an invocation must carry, the refusal each missing flag prints, and the
+ * conditional requirements (`--override` obliges `--reason`). `bin.ts` enforces
+ * from this table — it does not restate it — so the argument handling and the
+ * declaration cannot disagree. Adding a required flag is one edit here, and every
+ * reader of this table follows it.
+ *
+ * **The readers.** Two, and they are the two halves of a seam:
+ *
+ *   1. `bin.ts` — the CLI itself. It calls `missingRequirements` and prints the
+ *      declared message. This is what makes the table the requirement rather than
+ *      a description of one; a table nothing enforces is documentation, and
+ *      documentation is exactly what went stale.
+ *   2. `test/remedy-string-seam.test.ts` — the regression check. It extracts every
+ *      `halfcycle <verb> …` invocation the control service PRINTS and runs it
+ *      through the same `missingRequirements`. A future flag change fails that
+ *      test rather than an acceptance walk.
+ *
+ * **Why the seam, and which side owns the list (INV-001).** The control service
+ * writes the remedy strings; this CLI is what must accept them. `packages/bundle`
+ * is shippable and its import allowlist is exactly `{packages/core,
+ * packages/events}` — it cannot import the hosted control service (the moat check in
+ * `test/import-graph.test.ts` refuses even the NAME of a hosted package appearing in
+ * this package's source, which is why one is not written here), and control importing a
+ * published client installer to read its argument parser would invert the
+ * dependency and drag the installer into a hosted service. So the CLI owns the
+ * list, because the CLI is the thing that REJECTS: a requirement that lived
+ * anywhere else would be a copy of the enforcement rather than the enforcement.
+ * The test crosses the gap by READING control's source text off disk (an fs read,
+ * not an import — no build edge, no runtime edge, nothing shipped), the same way
+ * `test/command-set-parity.test.ts` reads a spec from the repo root.
+ *
+ * **What is deliberately NOT here.** No verb's full grammar, no optional flags, no
+ * usage text. This table answers exactly one question — *which flags must an
+ * invocation of this verb carry to be runnable* — because that is the question a
+ * remedy string makes a claim about. Widening it into a second argument-parsing
+ * home is the failure mode it exists to prevent.
+ */
+/** The verbs the CLI dispatches. Anything else after `halfcycle ` is unknown. */
+export declare const CLI_VERBS: readonly ["install", "check-drift", "build-record", "open-phase", "close-phase"];
+export type CliVerb = (typeof CLI_VERBS)[number];
+/** A flag every invocation of the verb must carry. */
+export interface RequiredFlag {
+    readonly flag: string;
+    /**
+     * Flags that satisfy the SAME requirement in the caller's place — the
+     * `--evidence` / `--override` choice on `open-phase`, where one basis or the
+     * other is required and neither is optional.
+     */
+    readonly orFlags?: readonly string[];
+    /** True when the flag needs a non-blank value after it. */
+    readonly takesValue: boolean;
+    /** The refusal the CLI prints when it is missing. One home for the wording. */
+    readonly missingMessage: string;
+}
+/** A requirement one flag's presence creates. */
+export interface ConditionalFlag {
+    readonly whenPresent: string;
+    readonly thenRequires: string;
+    readonly takesValue: boolean;
+    readonly missingMessage: string;
+}
+export interface VerbContract {
+    readonly verb: CliVerb;
+    readonly required: readonly RequiredFlag[];
+    readonly conditional: readonly ConditionalFlag[];
+}
+/** The contract for a verb, or `undefined` when the CLI has no such verb. */
+export declare function contractFor(verb: string): VerbContract | undefined;
+/** A requirement an invocation does not meet. */
+export interface Shortfall {
+    /** The flag that is missing (or present with no usable value). */
+    readonly flag: string;
+    /** The CLI's own refusal for it. */
+    readonly message: string;
+}
+/**
+ * The requirements `tokens` does not meet for `verb`, in declaration order.
+ *
+ * `tokens` is an argv slice from the CLI, or a printed invocation split on
+ * whitespace — the same function serves both, which is the point: the sentence a
+ * remedy prints is checked against the rule the binary enforces, not against a
+ * second copy of it.
+ *
+ * An unknown verb yields a single shortfall naming it. A remedy that names a verb
+ * this CLI does not have fails exactly like one that omits a flag, because to the
+ * developer who runs it the two are the same event.
+ */
+export declare function missingRequirements(verb: string, tokens: readonly string[]): Shortfall[];
+/**
+ * The declared refusal for one requirement — so a caller that checks a flag's
+ * VALUE (`--verdict` must be `clean` or `defects`) prints the same sentence the
+ * presence check prints, from the same place.
+ */
+export declare function requirementMessage(verb: CliVerb, flag: string): string;
+/**
+ * The shortest invocation of `verb` that this CLI accepts, with `phase` filled in
+ * and every required flag named — what a refusal tells a developer to run.
+ *
+ * RENDERED, not typed out. A remedy string built by hand is the defect this file
+ * was opened for; one built here cannot omit a flag, because the flags come from
+ * the same table the binary refuses on.
+ */
+export declare function runnableInvocation(verb: CliVerb, phase: string): string;
+//# sourceMappingURL=cli-contract.d.ts.map

package/dist/cli-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-contract.d.ts","sourceRoot":"","sources":["../src/cli-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,iFAAiF;AACjF,eAAO,MAAM,SAAS,kFAAmF,CAAC;AAE1G,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CAClD;AA0ED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAElE;AAED,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,CAyBxF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMvE"}

package/dist/close-phase.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Close-phase wiring — the CLI's call to `POST {baseUrl}/engagements/:id/accept`
+ * (walk 6 F-1, INV-022's sixth occurrence).
+ *
+ * WHY THIS EXISTS AT ALL, WHICH IS THE WHOLE POINT OF THE FINDING. Closing a phase
+ * has had a reachable route since PM-E6-T-18 and a working transition from `active`
+ * since W4-1 — but the only CLI that drove it is `phase-close-admin`, which ships
+ * inside the control plane and is therefore hosted-only (INV-001). A Connect client runs
+ * `npx halfcycle` in their own repo and can never run it. So the clean close was
+ * reachable by curl and by nothing the product ships, and every acceptance walk was
+ * pushed onto `open-phase --override` instead.
+ *
+ * `open-phase` and `close-phase` are the two halves of one cycle and now sit beside
+ * each other in one package, with one credential and one shape. That is the fix:
+ * not a new precondition, not a way to make a Studio gate satisfiable — the gate was
+ * never the problem — but the missing client half of a path that already worked.
+ *
+ * **This verb names no capability only Studio has.** No GitHub installation, no
+ * portal session, no operator picking anything up, and it never touches
+ * `delivering`. It is the same call in both topologies (`acceptPhase` is legal from
+ * `active` AND from `delivering`), which is what makes it safe to print in a refusal
+ * that both topologies can read — see `PhaseEntryConditionError`.
+ *
+ * WIRING, NOT MACHINERY — the same posture as `open-phase.ts`. The verdict is the
+ * caller's (INV-009: SOURCED from the acceptance walk, never inferred from "no guard
+ * fired"), the findings/detail consistency rule is the control plane's, and the
+ * derive-then-transition ordering is the orchestrator's. This module builds the
+ * request, sends it, and reports what came back.
+ *
+ * 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. `acceptanceOutcomeSchema` is the ONE home for the outcome's shape
+ * (INV-003), so the CLI validates what it builds against the same schema the route
+ * parses with. It never imports the control service.
+ */
+import { type AcceptanceOutcome, type PhaseCloseDecision } from '@halfcycle/events';
+import type { RepoCredential } from './open-phase.js';
+/** What `POST /engagements/:id/accept` returns on 200 (the fields the CLI reports). */
+export interface ClosedPhase {
+    engagementId: string;
+    /** The lifecycle status after the close — `closed`. */
+    status: string;
+}
+/**
+ * A refusal from the control plane, carried as an error the CLI can print whole.
+ *
+ * The two that matter and what they mean, because a status code alone sends people
+ * to the wrong fix:
+ *   - `409` — a refusal. THREE different ones now share this code (already closed;
+ *     outstanding work; the phase is not the one open), which is why `code` below
+ *     exists: the status alone stopped being enough to say what happened.
+ *   - `422` — the outcome is not a valid INV-009 outcome (most often the findings
+ *     count disagreeing with the number of `--finding` summaries). Nothing was
+ *     written: the derivation validates before any write.
+ */
+export declare class ClosePhaseRefused extends Error {
+    readonly status: number;
+    /**
+     * What the control plane's own store found outstanding in this phase, when the
+     * refusal was a `PhaseCloseConditionUnmet` (walk 7 `F-4`). Absent on every other
+     * refusal. Carried separately from `message` so the CLI can print the finding on
+     * its own line, the way `open-phase` prints a crossed entry finding.
+     */
+    readonly finding?: string | undefined;
+    /**
+     * The plane's own name for the refusal (`error` on the body) — e.g.
+     * `PhaseAlreadyClosed`, `PhaseCloseConditionUnmet`, `PhaseNotOpen`.
+     *
+     * WHY IT IS CARRIED (walk 8 `F-1`). The CLI used to read a bare `409` as "this
+     * phase is already closed" and print that as advice. Once a wrong phase NAME
+     * became its own 409, that line printed underneath a refusal saying the opposite
+     * — the plane said *phase 1 is open, close that one* and the CLI said *it is
+     * already closed*. Guessing a cause from a status code is how a remedy string
+     * comes to contradict the refusal above it; the code is read, not inferred.
+     */
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, 
+    /**
+     * What the control plane's own store found outstanding in this phase, when the
+     * refusal was a `PhaseCloseConditionUnmet` (walk 7 `F-4`). Absent on every other
+     * refusal. Carried separately from `message` so the CLI can print the finding on
+     * its own line, the way `open-phase` prints a crossed entry finding.
+     */
+    finding?: string | undefined, 
+    /**
+     * The plane's own name for the refusal (`error` on the body) — e.g.
+     * `PhaseAlreadyClosed`, `PhaseCloseConditionUnmet`, `PhaseNotOpen`.
+     *
+     * WHY IT IS CARRIED (walk 8 `F-1`). The CLI used to read a bare `409` as "this
+     * phase is already closed" and print that as advice. Once a wrong phase NAME
+     * became its own 409, that line printed underneath a refusal saying the opposite
+     * — the plane said *phase 1 is open, close that one* and the CLI said *it is
+     * already closed*. Guessing a cause from a status code is how a remedy string
+     * comes to contradict the refusal above it; the code is read, not inferred.
+     */
+    code?: string | undefined);
+}
+/**
+ * Record a phase's acceptance and close it.
+ *
+ * @param phase   the phase being closed, named explicitly — the lifecycle row has no
+ *                phase column (PM-E4-DEC-7), so the caller names what closed.
+ * @param outcome the SOURCED INV-009 verdict + findings.
+ * @param close   WHO is closing it and on what basis (walk 7 `F-4`). Required here
+ *                for the same reason `openPhase` requires its entry decision: there
+ *                is no argument-less way to move the phase axis, so an unattributed
+ *                close is unreachable from any caller that compiles.
+ *
+ * @throws ClosePhaseRefused on a 4xx the plane explained, 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 closePhase(credential: RepoCredential, phase: string, outcome: AcceptanceOutcome, close: PhaseCloseDecision): Promise<ClosedPhase>;
+//# sourceMappingURL=close-phase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"close-phase.d.ts","sourceRoot":"","sources":["../src/close-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;IAE9B;;;;;OAKG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;;OAUG;aACa,IAAI,CAAC,EAAE,MAAM;gBApBb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;;OAUG;IACa,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,WAAW,CAAC,CAwDtB"}

package/dist/create-engagement.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Create-engagement wiring — the installer's one HTTP call (#374).
+ *
+ * **IT IS TWO CALLS SINCE T-24 (#610), AND THEY LIVE HERE TOGETHER ON PURPOSE.**
+ * `createEngagement` starts a new engagement; `joinEngagement` obtains the caller
+ * their OWN credential for one that already exists, which is what a second developer
+ * cloning a repository needs and what nothing in this package asked for until now.
+ * The two answer the SAME question — *give me the four values this install needs* —
+ * over two routes, and the 200/201 bodies are field-for-field identical.
+ *
+ * A sibling module would therefore have had to re-decide four things that already
+ * have a home in this file: which non-2xx bodies are a plane refusal rather than a
+ * wrong address (`planeRefusal`), when the origin hint applies, that a blank-but-
+ * present identifier is refused, and what a refusal is thrown AS. Four copies is
+ * how two callers come to disagree about one contract (INV-003), and the disagreement
+ * would surface as the join path quietly accepting a body the create path refuses.
+ * So both entry points are thin, and `requestEngagementValues` below is the one home.
+ *
+ * `POST {baseUrl}/engagements` returns `{ engagementId, sessionToken, mcpUrl,
+ * guardUrl }`. This module is WIRING, not machinery: it makes that HTTP call and
+ * hands the values back. The installer then commits the id into
+ * `.halfcycle/bundle.json` (`writeBundlePin`, `install.ts`) and writes the token,
+ * the MCP origin and the id to the machine-level credential store OUTSIDE the
+ * repository (T-09, `engagement-credential.ts`).
+ *
+ * **THAT ROUTE IS NO LONGER UNAUTHENTICATED (T-21, `connect-signup-and-credential`).**
+ * This paragraph said it "ships PUBLIC and UNAUTHENTICATED"; it is now gated on a
+ * signed-in account and stamps that account as the engagement's owner, so an
+ * unauthenticated create is a 401 that creates nothing. `createEngagement` below
+ * takes an optional `credential` and sends it. **Obtaining one is `resolve-credential.ts`'s
+ * job since T-08** — `HALFCYCLE_TOKEN` in the environment, else the per-user store,
+ * else the browser handoff — and this module stays wiring: it neither resolves a
+ * credential nor decides what to do when one is refused. What it DOES own is telling
+ * a refusal apart from a wrong address (`CreateEngagementRefused` below), because
+ * that distinction is a property of the response and nothing further up the call
+ * stack can recover it from an `Error` message.
+ *
+ * **This paragraph said `.halfcycle/project.json` and that was never true**
+ * (corrected 2026-08-09, T-23 / issue #447). `writeProjectIdentity` calls
+ * `mintOrReadIdentity`, which writes `{projectId, rootCommit, remote, note}` and
+ * no engagement id — deliberately, under operator decision (au): no secrets in
+ * the committed identity. The claim was load-bearing: `services/delivery`'s MCP
+ * tool description was written against it and sent every client session to read a
+ * field that is not there, which walk 1 of the widening had to work around by
+ * hand. `note` (added W8-T-04, F-4) does not reopen (au) — it names no
+ * engagement, only that `projectId` is not one; see `identity.ts`.
+ *
+ * **THE TWO ORIGINS (T-22, #438).** `baseUrl` here is the CONTROL origin —
+ * `HALFCYCLE_SERVICE_URL`, which serves `POST /engagements` and
+ * `POST /board/enter-codes`. The MCP endpoint lives on a DIFFERENT deployed
+ * service, and control does not serve `/mcp` at all. Before T-22 one variable was
+ * read as the origin for all three routes, so no value satisfied it: pointed at
+ * control the installed `.mcp.json` named a 404 and the developer got no method
+ * context; pointed at delivery this call 404'd and no credential was ever minted.
+ * `npx halfcycle` could not produce a working install either way. The fix is that
+ * **the server declares the MCP origin** — the 201 carries `mcpUrl` — so the
+ * developer still configures exactly one address and the platform answers the
+ * question it already knows the answer to.
+ *
+ * The errors here NAME WHICH ORIGIN is wrong, in plain words. A developer whose
+ * variable points at the wrong half used to get a bare 404 and no way to tell
+ * which half of a two-service platform they had missed.
+ *
+ * INV-001: this file imports only Node builtins and the global `fetch` (Node 20).
+ * It never imports the control service — the create endpoint is an external HTTP
+ * contract, exactly like the runner is an external binary contract.
+ */
+/** The four values `POST /engagements` returns (Option A — the session credential
+ *  crosses once on create; `mcpUrl` and `guardUrl` are the server declaring where
+ *  its other two services live). */
+export interface CreatedEngagement {
+    engagementId: string;
+    sessionToken: string;
+    /**
+     * The origin serving the method-delivery MCP endpoint, as the platform reports
+     * it. Persisted as `HALFCYCLE_MCP_URL`; `.mcp.json` appends `/mcp` to it.
+     *
+     * Trailing slashes are stripped here so the one place that composes the MCP URL
+     * cannot produce `https://host//mcp`. Nothing else about the value is
+     * re-derived client-side: whether it is a usable origin is checked ONCE, on the
+     * control plane at boot (its `originProblem`), and a second copy of that grammar
+     * in a shippable package would be a second home for one rule — and, per INV-001,
+     * this file names no hosted path, not even in prose. What the client does
+     * instead is say plainly when the address does not answer — see `bin.ts`.
+     */
+    mcpUrl: string;
+    /**
+     * The origin serving the guard service's `/evaluate` endpoint, as the platform
+     * reports it — persisted as `GUARD_SERVICE_URL` (FW-4, F-29).
+     *
+     * A THIRD deployed service, and the installer cannot derive it any more than it
+     * could derive `mcpUrl`: control serves `/engagements`, delivery serves `/mcp`,
+     * guard serves `/evaluate`. Until the platform declared it, the installer wired
+     * a `PostToolUse` hook that runs the guard runner and wrote none of the runner's
+     * three variables — so every edit in a fresh Connect install produced a
+     * fail-open warning and no guard ever ran, while the install reported success.
+     *
+     * Trailing slashes are stripped here for the same reason they are on `mcpUrl`:
+     * the runner appends `/evaluate`, and one place composing the address cannot
+     * produce `https://host//evaluate`. Nothing else about the value is re-derived
+     * client-side — whether it is a usable origin is checked ONCE, on the control
+     * plane at boot, and a second copy of that grammar in a shippable package would
+     * be a second home for one rule.
+     */
+    guardUrl: string;
+    /**
+     * The origin the runner's telemetry POST goes to, as the platform reports it —
+     * `CONTROL_TELEMETRY_URL` on the wire (T-10, phase decision 13). Persisted to the
+     * machine-level store; `guard-runner.sh` sources the whole file, so no generated
+     * script names this variable directly.
+     *
+     * **OPTIONAL, unlike `mcpUrl`/`guardUrl` above — deliberately.** Those two are
+     * refused when absent because the install would otherwise ship a product that
+     * does nothing or a guard hook wired to no address. Telemetry is best-effort by
+     * design (`packages/runner/src/telemetry/emit.ts`: absent → emission silently
+     * disabled, guard loop unaffected), so a plane that has not configured
+     * `CONTROL_TELEMETRY_URL` yet must not fail every install over it — that would be
+     * a STRICTER posture than the thing being configured. **The key is ABSENT, not
+     * merely `undefined`-valued, when the plane sent none** — an optional TS property
+     * rather than `string | undefined`, so the two existing "full key set" tests in
+     * `create-engagement.test.ts` (whose fixture server does not send this field) see
+     * the same four keys they always have, and only a fixture that adds the field
+     * gains the fifth.
+     */
+    controlTelemetryUrl?: string;
+}
+/**
+ * A refusal the CONTROL PLANE wrote — the origin is right, and it declined (T-08).
+ *
+ * Carried as its own error class so a caller can tell "your credential was refused"
+ * apart from "that address is not a control plane", which are the same
+ * `!res.ok` today and want completely different next actions. `bin.ts` branches on
+ * `authRefused` to decide whether signing in again can possibly help.
+ *
+ * **THE JOIN CALL THROWS THIS TOO, AND THE NAME WAS DELIBERATELY NOT CHANGED (T-24).**
+ * The class carries FACTS — a status, the plane's own sentence, the discriminant —
+ * and those are the same facts on both routes, so a second class would have been a
+ * second home for the same three fields and for `authRefused`'s derivation. Renaming
+ * it to something route-neutral was the other option and was rejected: it is an
+ * exported symbol of this package's public entry, and churning a published name to
+ * improve how one new call site reads is a poor trade. The name is create-shaped for
+ * historical reasons; what it means is *the plane refused*.
+ */
+export declare class CreateEngagementRefused extends Error {
+    /** The HTTP status control answered with. */
+    readonly status: number;
+    /** Control's own client-safe sentence, forwarded verbatim. */
+    readonly serverMessage: string;
+    /** The `error` discriminant, when the envelope carried one. */
+    readonly errorCode: string | undefined;
+    constructor(
+    /** The HTTP status control answered with. */
+    status: number, 
+    /** Control's own client-safe sentence, forwarded verbatim. */
+    serverMessage: string, 
+    /** The `error` discriminant, when the envelope carried one. */
+    errorCode: string | undefined, message: string);
+    /**
+     * Is this a refusal of the CALLER's credential — the arm signing in again can fix?
+     *
+     * `PublicStartDisabled` is excluded even though it is a 403, and that exclusion is
+     * the whole reason this is a method rather than a status comparison at the call
+     * site: the flag gates the DEPLOYMENT, identically for every caller, so no
+     * credential and no sign-in changes the answer. Treating it as an auth refusal
+     * would send a developer through a browser handoff to arrive at the same 403.
+     *
+     * **THIS IS THE CREATE ROUTE'S DERIVATION AND THE JOIN CALLER MUST NOT USE IT
+     * (T-24).** On the join route a 403 has two causes that share a status AND a
+     * discriminant (`error: 'Forbidden'`), so nothing on this object can tell them
+     * apart: the credential may be a live engagement token carrying no account, or the
+     * engagement id may not resolve. Signing in again cannot fix the second, and
+     * treating it as though it could would discard a good credential, walk the
+     * developer through a browser, and arrive at the identical 403 — a remedy that
+     * loops. `bin.ts`'s join path therefore retries on `401` ALONE, at the call site,
+     * where the reason can be written down. See `joinPinnedEngagement` there.
+     */
+    get authRefused(): boolean;
+}
+/**
+ * Create a fresh engagement against the platform's public create endpoint.
+ *
+ * **THE ROUTE REQUIRES A SIGNED-IN CALLER SINCE T-21** — an unauthenticated create
+ * is a 401 and creates nothing, which is the feature's first acceptance criterion.
+ * This function therefore SENDS a credential when it has one.
+ *
+ * **OBTAINING one is `resolve-credential.ts`'s, and it EXISTS (T-08, landed).** This
+ * paragraph said it "is T-08's half", written while it was still owed — and the file
+ * header 165 lines above was corrected when T-08 landed while this one was not, so a
+ * reader who opened the function rather than the file top was told the browser
+ * handoff did not exist yet. Same file, two claims, one of them false: the same
+ * stale-claim shape this task corrected twice on the plane's own refusal messages.
+ * (INV-001 keeps this file naming no hosted path, not even in prose — the guard in
+ * `import-graph.test.ts` caught the first draft of this very sentence doing it.)
+ *
+ * @param baseUrl  The CONTROL origin (e.g. `https://control.halfcycle.ai`).
+ *                 The request is `POST {baseUrl}/engagements`.
+ * @param name     Optional project name; the server defaults a blank/absent name.
+ * @param credential Optional bearer credential, from `obtainCredential`. **EITHER
+ *                 credential class works**, and that is a property of control's
+ *                 `resolveAccount` rather than an accident here: an ACCOUNT
+ *                 CREDENTIAL from the browser handoff, or an ENGAGEMENT TOKEN from
+ *                 an install this person already has. Blank/absent sends no header
+ *                 at all — a missing credential must look identical to the server as
+ *                 no header, never `Bearer `.
+ * @returns        `{ engagementId, sessionToken, mcpUrl, guardUrl }` on 201.
+ * @throws         `CreateEngagementRefused` when the PLANE refused (its own envelope,
+ *                 no origin hint — the origin demonstrably answered); a plain `Error`
+ *                 when the address is in question (a 404, an unreachable host, an
+ *                 unreadable body), which is the only case that carries
+ *                 `CONTROL_ORIGIN_HINT`. Either way the installer must NOT proceed to
+ *                 write a half-formed credential or a `.mcp.json` pointing nowhere.
+ */
+export declare function createEngagement(baseUrl: string, name?: string, credential?: string): Promise<CreatedEngagement>;
+/**
+ * Obtain a credential of the CALLER'S OWN for an engagement that already exists
+ * (T-24, #610) — `POST {baseUrl}/engagements/{engagementId}/join`.
+ *
+ * **THE SECOND DEVELOPER'S PATH, AND UNTIL NOW NOTHING IN THIS PACKAGE WALKED IT.**
+ * The route shipped with T-06 and was tested at the store and at the route; no client
+ * called it, so *"a second developer clones and just works"* was reachable by HTTP and
+ * unreachable by the product. `bin.ts` calls this when the committed pin names an
+ * engagement and this checkout holds no credential for it.
+ *
+ * WHAT COMES BACK IS THE CALLER'S, NOT A COPY OF ANYBODY'S. The plane mints a fresh
+ * secret bound to `(engagement, this account)`; the first developer's credential is a
+ * different subject and is untouched. That is a property of the plane, asserted where
+ * it can be seen — in the store, after the window that would have expired a rotated
+ * predecessor — and not something this wiring can claim for itself.
+ *
+ * **A REFUSAL HERE IS NEVER AN EXISTENCE ANSWER.** The plane answers 403 with a
+ * constant sentence both when the caller's credential carries no account and when the
+ * id resolves to nothing, so this client cannot know which — and must not compose a
+ * message that implies it found out. It forwards the plane's own sentence and adds
+ * only facts local to this machine. See `bin.ts`'s join path for the one sentence it
+ * adds and why that sentence is a constant.
+ *
+ * @param baseUrl       The CONTROL origin, exactly as `createEngagement` takes it.
+ * @param engagementId  The id from the committed pin. Percent-encoded into the path:
+ *                      it is read from a file on disk, so it is not this function's
+ *                      place to assume it is a well-formed uuid — a value with a `/`
+ *                      in it must address one route badly, never a different route.
+ * @param credential    Optional bearer credential, from `obtainCredential`.
+ * @returns             `{ engagementId, sessionToken, mcpUrl, guardUrl }` on 200 —
+ *                      the same four fields create returns, which is why the installer
+ *                      needs no second branch downstream of this call.
+ */
+export declare function joinEngagement(baseUrl: string, engagementId: string, credential?: string): Promise<CreatedEngagement>;
+//# sourceMappingURL=create-engagement.d.ts.map

package/dist/create-engagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-engagement.d.ts","sourceRoot":"","sources":["../src/create-engagement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH;;oCAEoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,6CAA6C;aAC7B,MAAM,EAAE,MAAM;IAC9B,8DAA8D;aAC9C,aAAa,EAAE,MAAM;IACrC,+DAA+D;aAC/C,SAAS,EAAE,MAAM,GAAG,SAAS;;IAL7C,6CAA6C;IAC7B,MAAM,EAAE,MAAM;IAC9B,8DAA8D;IAC9C,aAAa,EAAE,MAAM;IACrC,+DAA+D;IAC/C,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7C,OAAO,EAAE,MAAM;IAMjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,WAAW,IAAI,OAAO,CAGzB;CACF;AA2CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAW5B"}