halfcycle 0.4.14 → 0.4.15

package/dist/install.d.ts

@@ -22,7 +22,8 @@
  * Halfcycle's scaffold contents.
  */
 import { BUNDLE_PIN_REL, MCP_REGISTRATION_REL, MCP_SERVER_KEY, SETTINGS_REL, WRITE_CAPABLE_TOOLS } from '@halfcycle/core';
-import { lineKey, type ManifestFile } from './install-manifest.js';
+import { type PlannedProjectIdentity } from './identity.js';
+import { lineKey, type InstallManifest, type ManifestFile } from './install-manifest.js';
 import { type ClaudeSettings, type StatusLineSetting } from './merge-settings.js';
 export type EngagementType = 'self-build' | 'client';
 export interface BundlePin {
@@ -376,6 +377,8 @@ export { BUNDLE_PIN_REL };
 /** The crew roster. Exported for the monorepo uninstall (`self-build-install` AC8),
  *  which must name this one path to check its bytes rather than remove it by path. */
 export declare const CREW_ROSTER_REL = ".halfcycle/crew.json";
+/** The captured-fixture index, written only when absent. */
+export declare const CAPTURED_INDEX_REL = "test/fixtures/captured/manifest.json";
 /**
  * The three files the installer merges into rather than owns. `SETTINGS_REL` lives
  * with the hook table in `@halfcycle/core` and is re-exported here, as is
@@ -385,6 +388,15 @@ export { SETTINGS_REL, WRITE_CAPABLE_TOOLS };
 export declare const GITIGNORE_REL = ".gitignore";
 /** The attributes file the installer appends its line-ending rules to. */
 export declare const GITATTRIBUTES_REL = ".gitattributes";
+/**
+ * The connection-headers helper an earlier version generated and `.mcp.json` named
+ * (T-24, #446). RETIRED by `windows-client-seat`: Claude Code runs a `headersHelper`
+ * under `cmd.exe` on Windows, where this POSIX script cannot run, so the registration
+ * now names a `node` command (`MCP_HEADERS_HELPER_COMMAND`) and the script's work is
+ * the vendored runner's `mcp-headers` verb. Declared here, above the list it joins,
+ * because that list is read at module load.
+ */
+export declare const RETIRED_MCP_HEADERS_HELPER_REL = ".halfcycle/mcp-headers.sh";
 export interface ClosedWriteSet {
     /** Files the installer writes whole. */
     readonly files: ReadonlySet<string>;
@@ -487,6 +499,65 @@ export declare function closedWriteSet(): ClosedWriteSet;
  * (`startManifest`), so a committed record cannot vouch for a path that is not ours.
  */
 export declare function bytesAreOurs(path: string, bytes: Uint8Array, recorded: ManifestFile | undefined, writeSet: ClosedWriteSet): boolean;
+/**
+ * Read the manifest an earlier install wrote, for this run to carry forward.
+ *
+ * AN UNREADABLE ONE IS TREATED AS ABSENT, and that is the safe direction here (it is
+ * the opposite of uninstall, which refuses one). This run is about to rewrite it
+ * from what it observes; the cost of reading it as absent is that this run is
+ * treated as the first manifest run, which claims LESS — nothing it cannot prove —
+ * and marks the merged files adopted rather than created, which makes uninstall
+ * remove less. Refusing the install over a file the install is about to rewrite
+ * would leave a tree with a corrupt manifest no command could repair.
+ */
+declare function readPreviousManifest(targetRepo: string): InstallManifest | null;
+/** The bytes a path holds once the install has run (see `noteFile`). */
+type BytesAfter = (rel: string) => Uint8Array;
+/**
+ * Which files set up here git would leave out of a commit (`setup-travel-warning`), or
+ * `null` when there is nothing to say.
+ *
+ * THE PATHS COME FROM THE MANIFEST THIS RUN WROTE, NEVER FROM THE HOOK TABLE (decision
+ * 15). The table is what a machine runs; this is every file the installer set up, and
+ * a new installer path joins it by being recorded, which `assertManifestInWriteSet`
+ * already holds to the closed write set. So: the manifest's files except the
+ * per-machine one, the merged files it records, and the manifest itself — less this
+ * run's collisions (a developer's own file at one of our names was not set up here,
+ * even when an earlier manifest recorded the name) and less anything absent from disk.
+ *
+ * A path is dropped too when a directory above it, below `targetRepo`, is a symbolic
+ * link or holds a `.git` entry (a submodule or nested repository). Git refuses the
+ * whole batch over one such path, so a symlinked or submodule `.claude` would
+ * otherwise silence an ignored `.halfcycle/` or `.mcp.json`. A symlinked FILE is
+ * answered normally and stays.
+ *
+ * The named file is `.claude/settings.json` when it is ignored, else the first ignored
+ * path in sorted order. Reads only: nothing here writes to the tree or to git.
+ */
+declare function findNotShared(targetRepo: string, manifest: InstallManifest, collidedPaths: readonly string[]): NotShared | null;
+/** A planned command stub: a `PlannedFile` plus whether a collision is an edit of ours (E8). */
+export interface PlannedCommand extends PlannedFile {
+    readonly editedCollided: boolean;
+}
+/**
+ * One file the installer's plan decided about (`install-plan.ts`), at a path inside the
+ * folder. `text` is what the file holds once the plan is applied: the bytes written for
+ * `written`, the bytes already there for `skipped`, and for `collided` the bytes that
+ * would have been written, which are not. `replacedExisting` is true only when a
+ * DIFFERING file of ours is overwritten, never on a fresh write or an identical one.
+ */
+export interface PlannedFile {
+    readonly rel: string;
+    readonly text: string;
+    readonly outcome: CopyOutcome;
+    readonly replacedExisting: boolean;
+}
+/**
+ * The ONE write a planned file gets (`setup-preview-and-doctor` AC1): its planned bytes,
+ * at its path, only when the plan says `written`, and only inside the write allowlist.
+ * The decision was taken by the plan; this never re-reads the file to take it again.
+ */
+export declare function putPlannedFile(targetRepoRoot: string, planned: PlannedFile): void;
 /**
  * The write outcome for one target path under the copy set.
  * - `written`  — the file did not exist and was created.
@@ -503,6 +574,19 @@ type CopyOutcome = 'written' | 'skipped' | 'collided';
  *  whose enforcement nothing exercises is the shape this area keeps paying for.
  *  It is not an API: every caller inside this module goes through `recordOwned`. */
 export declare function writeOwned(targetAbsPath: string, targetRepoRoot: string, content: string): CopyOutcome;
+/** The four path buckets the install accumulates and returns. */
+interface MutableReport {
+    writtenPaths: string[];
+    skippedPaths: string[];
+    mergedPaths: string[];
+    collidedPaths: string[];
+    /** A SUBSET of `collidedPaths` (E8): the previous manifest already named this
+     *  path as ours. See `InstallResult.editedCollidedPaths`. */
+    editedCollidedPaths: string[];
+    /** A SUBSET of `writtenPaths`, not a fifth bucket: files of ours that already
+     *  existed, differed, and were overwritten (`GWF-2`). See `recordOwnedGenerated`. */
+    replacedPaths: string[];
+}
 /**
  * The `permissions.deny` patterns a fresh install seeds (F-23(a), operator
  * decision note 2026-08-10). THE ONE HOME of the list — the method's served step
@@ -713,6 +797,12 @@ export type RetiredFileRemoval = 'removed' | 'kept-foreign' | 'kept-uncommitted'
  * otherwise-successful install.
  */
 export declare function removeLegacyCiStanza(targetRepo: string): RetiredFileRemoval;
+/** The removal half: only ever reached for a file the plan decided `removed`. Best-effort. */
+export declare function removePlannedRetiredFile(targetRepo: string, rel: string): 'removed' | 'failed';
+/** The path of the CI stanza an earlier version wrote; nothing writes it any more. */
+export declare const LEGACY_CI_STANZA_REL = ".halfcycle/ci-stanza.yml";
+/** `removeLegacyCiStanza`'s decision, by reading alone. */
+export declare function planLegacyCiStanzaRemoval(targetRepo: string): RetiredFileRemoval;
 /**
  * **THE INSTALLER WRITES NO `.env.example`, AND THIS IS WHERE THAT GENERATOR WAS.**
  *
@@ -776,6 +866,8 @@ export { MCP_REGISTRATION_REL, MCP_SERVER_KEY };
  * with no MCP origin rewrites no registration, so it removes nothing.
  */
 export declare function removeRetiredMcpHeadersHelper(targetRepo: string): RetiredFileRemoval;
+/** `removeRetiredMcpHeadersHelper`'s decision, by reading alone. */
+export declare function planMcpHeadersHelperRemoval(targetRepo: string): RetiredFileRemoval;
 /**
  * THE ONE HOME of *which generated files this installer claims as its own, and by
  * what evidence* (#1103). Every entry is a client-tree path this package
@@ -818,6 +910,7 @@ export declare const OWNED_GENERATED_HEADERS: {
     readonly '.claude/hooks/guard-runner.sh': "# Governance hook wrapper — generated by";
     readonly '.claude/hooks/user-prompt-reminder.sh': "# UserPromptSubmit house-rule reminder — generated by";
     readonly '.claude/hooks/user-prompt-scope.sh': "# Typed scope approval — generated by";
+    readonly '.claude/hooks/user-prompt-findings.sh': "# Findings hand-over — generated by";
     readonly '.claude/hooks/session-end-marker.sh': "# Session-end marker cleanup — generated by";
     readonly '.claude/hooks/session-start-marker.sh': "# Session-start marker — generated by";
 };
@@ -870,6 +963,32 @@ export declare function lineEndingOf(text: string): '\n' | '\r\n';
  * CRLF script, which is why `.gitattributes` pins them LF in every clone.
  */
 export declare function inLineEndingOf(existing: string | null, generated: string): string;
+/**
+ * Ensure `.gitignore` carries every required entry, reconciled BY CONTENT — a
+ * newer required entry is appended even on a tree an older install wrote.
+ *
+ * BEST-EFFORT BY DESIGN: a write failure (e.g. a read-only `.gitignore`) does NOT
+ * throw here — and since T-09 there is no longer a hard gate downstream of it,
+ * because the thing that gate protected (a bearer token in the tree) is not written
+ * any more. What is left on this path is per-device state and Zone-B, whose worst
+ * case is a noisy `git status`, not a leaked credential. `failed` is reported so the operator
+ * sees the reconcile did not land.
+ *
+ * @returns the outcome for the report bucket.
+ */
+export declare function planGitignore(targetRepo: string): PlannedMerge;
+/** The write half of the `.gitignore` reconcile: the planned bytes, or `failed`. Never throws. */
+export declare function putPlannedGitignore(targetRepo: string, planned: PlannedMerge): CopyOutcome | 'failed';
+/**
+ * A planned reconcile of a file the installer appends to (`.gitignore`, `.gitattributes`):
+ * the text before, the text after (`null` when there is none to read), and the outcome.
+ * `failed` means the plan already knows the write cannot land; nothing is attempted.
+ */
+export interface PlannedMerge {
+    readonly before: string | null;
+    readonly after: string | null;
+    readonly outcome: CopyOutcome | 'failed';
+}
 /**
  * The header line every `.gitattributes` block this installer appends opens with
  * (`windows-install-hygiene.md`, AC1). Git for Windows usually clones with
@@ -877,6 +996,99 @@ export declare function inLineEndingOf(existing: string | null, generated: strin
  * line endings; the rules under this header pin them to LF in every clone.
  */
 export declare const GITATTRIBUTES_HEADER = "# Halfcycle \u2014 generated scripts keep LF line endings";
+/** A file's text, or `null` when it is absent or cannot be read as a file. */
+export declare function readTextOrNull(path: string): string | null;
+/**
+ * Ensure `.gitattributes` carries every required LF rule, reconciled BY CONTENT the
+ * way `reconcileGitignore` reconciles `.gitignore`: a missing rule is appended under
+ * the header, a rule already present (the developer's or an earlier run's) is never
+ * appended twice, and no existing byte is rewritten.
+ *
+ * Routed through `writeAllowlisted`, so this write is held to `WRITE_ALLOWLIST` —
+ * which `reconcileGitignore`'s bare write is not. BEST-EFFORT, as that one is: a
+ * failure (a read-only file, or the allowlist refusing) is caught and returned as
+ * `failed`, and the install goes on. The worst case of a missing rule is a hook
+ * script a Windows clone checks out with CR line endings.
+ *
+ * A SYMBOLIC LINK at `.gitattributes` is refused as `failed`, never written through:
+ * the allowlist checks the path's name, and a link could point outside the tree.
+ */
+export declare function planGitattributes(targetRepo: string): PlannedMerge;
+/** The write half of the `.gitattributes` reconcile, held to the allowlist. Never throws. */
+export declare function putPlannedGitattributes(targetRepo: string, planned: PlannedMerge): CopyOutcome | 'failed';
+/**
+ * Decide the committed pin's bytes (`writeBundlePin` writes them). Reads only.
+ *
+ * THE CREATOR'S ID IS CARRIED FORWARD, and that is the whole reason this function reads
+ * before it writes. The pin is rewritten from scratch on every install, and only the
+ * create arm supplies the id (E1, #1598); a re-run, a join and a refused join supply
+ * none. Composing a fresh pin from one of those would silently DELETE the record the
+ * create wrote — the exact disappearance this field exists to prevent — and letting
+ * one of them supply its own acting account (the pre-E1 rule) made a joiner in a clone
+ * rewrite the committed owner to itself. So the previous value wins over any supplied
+ * one, and a pin carrying the pre-E1 name `accountId` is read through
+ * `pinCreatedByAccountId` and written back as `createdByAccountId`.
+ *
+ * **`installedAt` IS CARRIED FORWARD TOO, ALWAYS, WITHIN THE SAME ENGAGEMENT (F-02,
+ * #1192 — H-04 walk observation D, 2026-09-17).** The field means THE MOMENT THIS
+ * ENGAGEMENT WAS FIRST SET UP IN THIS REPOSITORY — not the moment the last install ran,
+ * and not anything about a machine. Until this fix it was `new Date()` on every write, so
+ * `npx halfcycle` in a second clone of an already-set-up project (the join arm: same
+ * engagement, same version, same account) rewrote the committed pin with a new timestamp
+ * and left that clone's tree dirty with a change nobody meant to commit — and the
+ * criterion-8 test pinned that as a documented exemption rather than as the defect it
+ * was. A committed file must not carry a per-run value: what it records is a fact about
+ * the repository, which every clone shares, so a re-run that changes no fact must leave
+ * the bytes alone. The rule is therefore the same one the creator's id already follows —
+ * carried within the same engagement, fresh for a different one — and a re-install of the
+ * same engagement at the same version by any account is byte-identical. A version
+ * upgrade changes `version` and nothing else: the set-up moment did not move because the
+ * installer did.
+ *
+ * IT IS CARRIED ONLY WITHIN THE SAME ENGAGEMENT. A run that installs a different
+ * engagement id into this repository (an explicit id argument, or a join) is a different
+ * tenancy, and the previous engagement's creator is not a fact about it: such a run is
+ * not a create, so the pin records nothing rather than a name inherited from an
+ * engagement it has nothing to do with. The same
+ * holds for the set-up moment: a repository re-pointed at another engagement was set up
+ * for THAT engagement now.
+ *
+ * A pin that cannot be read is treated as no pin. This is advisory provenance, and an
+ * unparseable file must not fail an install. A previous pin whose `installedAt` is
+ * missing or blank gets this run's clock — the only value there is — rather than an
+ * empty field.
+ */
+declare function planBundlePin(targetRepoRoot: string, version: string, engagementId: string, engagementType: EngagementType, createdByAccountId: string | undefined, methodVersion: string | undefined): PlannedFile;
+/**
+ * The preview's best prediction for the committed pin, read from this repository's OWN
+ * pin and credential store rather than from the service (W-10 R2, #F-65; tightened by
+ * review R-F65 finding 1). A preview never signs in, so it has no FRESH answer for the
+ * method version — and a real run only ever carries the committed pin's method version
+ * forward UNCHANGED, with no network call of its own, on exactly one arm: the RE-USE
+ * arm (`bin.ts`), reached when this machine already holds a complete, usable credential
+ * for this SAME engagement (`readPinnedEngagement`), because `toCredential` never
+ * stores a method version in that local store at all, so `planBundlePin` always falls
+ * back to the previous pin's own value there (`carriedMethodVersion`, above). Every
+ * OTHER real run — a join from a second clone, a fresh container, a credential this
+ * machine never had — asks a live plane for a method version this offline preview
+ * cannot know, and the plane can answer something the committed pin does not expect (a
+ * project whose phase moved on since this pin was last written). Claiming `leave` there
+ * is a guess, not a prediction, and review R-F65 found it wrong in exactly that shape:
+ * a repository pinned to an older method, joined while the service now serves a newer
+ * one, previewed as unchanged and then was not. So this function predicts `leave` (or
+ * an exact `change`) ONLY on the re-use arm; every other case returns `null`, and
+ * `install-plan.ts` leaves the row `PENDING` — `change` by existence alone — exactly as
+ * AC1/AC3 already document for a file whose bytes need the service's fresh answer.
+ * `home` is the preview's own (a test's throwaway, or the real one), read-only, same as
+ * everything else `planInstall` already reads from a folder it never signs in from.
+ */
+export declare function planBundlePinPreview(targetRepoRoot: string, version: string, home?: string): PlannedFile | null;
+/**
+ * Write the committed pin a plan decided (`planBundlePin`), through `writeAllowlisted`
+ * alone, so identical bytes are no write and a changed pin lands in `writtenPaths`. One of
+ * the two functions allowed to write the pin.
+ */
+declare function writeBundlePin(targetRepoRoot: string, planned: PlannedFile, writtenPaths: string[]): void;
 /**
  * Rewrite the committed pin's `methodVersion` field after `close-phase` or
  * `open-phase` moves the project forward between phases
@@ -1070,6 +1282,179 @@ export declare function checkDrift(targetRepoRoot: string): {
     /** The method version the committed pin recorded (T-01), or `null` when none was. */
     methodVersion: string | null;
 };
+/**
+ * Create `.halfcycle/project.json` (committed identity) when there is none. The file
+ * carries no secret — only the minted id and the repo's root-commit/remote
+ * fingerprint (criterion 2 / operator decision (au)).
+ *
+ * ONE RULE: AN EXISTING `project.json` IS NEVER WRITTEN (`project-identity-reuse`
+ * AC1). Until the onboarding fix wave (T-05, from review R-03) this reconciled by
+ * bytes and rewrote any file that differed from what this installer would write —
+ * an older installer's file without `note`, CRLF line endings, an extra field — by
+ * truncate-then-write, which also raced a concurrent install's read of the same
+ * file. Now a present file is `skipped` whatever its bytes, and an absent one is
+ * created through `createProjectIdentityFile`, whose `linkSync` never replaces a
+ * file that appeared in between. The cost, accepted: an older file never gains the
+ * current `note` (W8-T-04, F-4); a fresh install still writes it.
+ *
+ * **ONE EXCEPTION (#1744, G1): `repairRemoteCredential` runs on a present file
+ * before it is reported `skipped`**, and rewrites it ONLY when its `remote` still
+ * carries a credential — review R-34, F1: this is THE real install path every
+ * run takes (`bin.ts` calls `install()` on every arm), and the first cut of this
+ * fix lived only in `mintOrReadIdentity`, which nothing here ever called, so a
+ * real run left the credential in place. Best-effort and silent either way.
+ *
+ * **WRITTEN FROM THE PLAN (`setup-preview-and-doctor` AC1).** What happens here was
+ * decided by `planProjectIdentity` before anything was written: `add` creates the file
+ * with the identity the plan minted, `change` is the G1 repair with the plan's bytes,
+ * `leave` writes nothing. The create arm's `claimFolderId` calls this same function
+ * with `probe` set, so its write-access check runs on every call, as it always has.
+ *
+ * @returns the outcome for the report bucket: `written` for `add`, else `skipped`.
+ */
+export declare function writeProjectIdentity(targetRepo: string, planned: PlannedProjectIdentity, probe?: boolean): CopyOutcome;
+/**
+ * Persist the engagement's credential to the MACHINE-LEVEL store, outside this
+ * repository (T-09) — `~/.halfcycle/engagements/<id>/env`, owner-only.
+ *
+ * **The refusal contract that used to live here is RETIRED, not forgotten.**
+ * Operator decision (av) made this function throw when `.gitignore` did not cover
+ * `.env.local`, so a live bearer token was never written into a tree that would
+ * commit it on the next `git add .`. Nothing is written into the tree any more, so
+ * that refusal now protects a file that does not exist — and a builder who kept it
+ * would refuse installs over its absence. The property it defended is stronger
+ * without it: the credential cannot be committed because it is not there, rather
+ * than because a tracked ignore file says not to.
+ *
+ * NON-DESTRUCTIVE, still: the store is APPEND-RECONCILED by key
+ * (`reconcileEnvText`), because Studio's provider writes its own keys into the same
+ * per-engagement file — `CONTROL_TELEMETRY_TOKEN` and `HALFCYCLE_GUARD_EVAL_LOG_DIR`
+ * — and a whole-file overwrite here would silently delete them.
+ *
+ * **`CONTROL_TELEMETRY_URL` is NOT in that "Studio's own key" set, and saying it was
+ * would be a false claim (review finding, T-10 follow-up).** This docblock named
+ * `CONTROL_TELEMETRY_*` as a whole family until this correction, which was true
+ * before T-10 and stopped being true once `CONTROL_TELEMETRY_URL` joined
+ * `ENGAGEMENT_ENV_KEYS` — it is reconciled BY THIS installer now, exactly like
+ * `HALFCYCLE_TOKEN`, and a Studio-written value for it is overwritten on the next
+ * Connect install rather than preserved. `CONTROL_TELEMETRY_TOKEN` alone is the
+ * still-genuinely-foreign example.
+ *
+ * The engagement id travels into the store as a value, and no name reaches the
+ * client's tree at all: since 2026-08-30 the installer generates no env scaffold, so
+ * what this engagement was created AGAINST is recorded only here, at machine level.
+ */
+declare function writeEngagementCredential(credential: DeviceCredential, engagementId: string, home?: string): CopyOutcome;
+/**
+ * What the installer's plan expects the machine-level store to hold once the credential
+ * is written, and whether that write changes it — computed with the store's own
+ * reconcile (`reconcileEnvText`), reading the store and writing nothing. The legacy
+ * migration is PLANNED against `storedAfter`; it is still DECIDED again at apply time
+ * against the store read back from disk (`migrateLegacyEnvLocal`'s rule).
+ */
+export declare function planEngagementCredential(credential: DeviceCredential, engagementId: string, home?: string): {
+    outcome: CopyOutcome;
+    existed: boolean;
+    storedAfter: Record<string, string>;
+};
+/** Where the credential used to live, before T-09. Named once, and only the
+ *  migration below may use it. */
+export declare const LEGACY_ENV_LOCAL_REL = ".env.local";
+/** What the legacy-credential migration did, for the installer's report. */
+export interface LegacyMigration {
+    outcome: 'removed' | 'stripped' | 'failed' | 'absent' | 'kept';
+    /**
+     * On `kept` ONLY: the Halfcycle keys the in-tree file carries that the
+     * machine-level store does not, i.e. the values that would have been destroyed.
+     * Empty on every other outcome.
+     */
+    unbacked: string[];
+    /**
+     * On `kept` ONLY: which of `CREDENTIAL_REQUIRED_KEYS` this file cannot supply —
+     * the actual REASON the store was not written, derived rather than narrated. A
+     * pre-#439 repo is missing `HALFCYCLE_MCP_URL` and may or may not be missing
+     * `GUARD_SERVICE_URL`; a message that guesses which would be wrong for half of them.
+     */
+    missingForAdoption: string[];
+    /** On a `stripped` DECISION only: the file's text with our keys taken out. */
+    keptText?: string;
+}
+/**
+ * DECIDE (and since the plan-then-apply split, only decide; `applyLegacyMigration`
+ * writes) taking the seven Halfcycle keys OUT of a pre-T-09 `.env.local` — but ONLY once the
+ * machine-level store demonstrably holds them — and delete the file if that is all
+ * it held.
+ *
+ * **This is the step that makes the feature true for a repository that already
+ * exists.** Writing the machine-level store while leaving the old file in place
+ * would satisfy every "a fresh install writes no credential" assertion and leave a
+ * live bearer token in the tree of every repo installed before today — the exact
+ * exposure this task closes, surviving in the population that actually has one.
+ *
+ * ---------------------------------------------------------------------------
+ * **THE RULE IS: NEVER REMOVE THIS REPOSITORY'S COPY UNLESS A COPY NOW EXISTS
+ * OUTSIDE IT.** `stored` is the machine-level store READ BACK FROM DISK after the
+ * write at step 7c, and this function strips nothing that is not in it.
+ *
+ * This is not defensive dressing; it is the review blocker. The first version ran
+ * unconditionally, on the stated ground that a repo reaching this point must have
+ * supplied a credential. It need not, and **the population where it does not is
+ * exactly the population the migration exists for.** `toCredential` yields a
+ * credential only when ALL FOUR of `HALFCYCLE_SERVICE_URL`, `HALFCYCLE_TOKEN`,
+ * `HALFCYCLE_MCP_URL` and `GUARD_SERVICE_URL` are present; `HALFCYCLE_MCP_URL`
+ * entered the write set on 2026-08-08 (#439) and `GUARD_SERVICE_URL` on 2026-08-10
+ * (FW-4). Every engagement installed before those dates has a `.env.local` holding
+ * a live token and NOT those keys — so the store write was skipped, and this
+ * function deleted the only copy of a session token that cannot be re-minted, then
+ * reported *"REMOVED — the credential now lives outside this repository"*, at exit
+ * 0, when nothing had been written outside the repository at all.
+ *
+ * Keying on the store's CONTENTS rather than on "was a credential passed in" is
+ * deliberate: a partial or truncated write reads as missing keys here and takes the
+ * same refusal, whereas the `credential !== undefined` test would call it a success.
+ * The comparison is PRESENCE, not value equality — a store holding a NEWER token
+ * for the same engagement must still be allowed to retire the stale in-tree copy,
+ * which is the whole point; what may never happen is dropping a key the store has
+ * no value for at all.
+ *
+ * And the copy that remains must be USABLE, not merely present — see the two
+ * conditions at the refusal below. A store that holds some of the keys but cannot
+ * produce a whole `DeviceCredential` leaves the NEXT command with nothing in either
+ * place, which is a quieter failure than this one.
+ *
+ * ---------------------------------------------------------------------------
+ * **IT REMOVES OUR KEYS, NOT THE DEVELOPER'S FILE.** `.env.local` is where a
+ * developer keeps their own `DATABASE_URL` — that is why the write path was made
+ * append-reconciling in the first place (#375) — so deleting it wholesale would
+ * destroy work the installer never owned. Every line that is not one of ours
+ * survives byte-for-byte, and the file is `unlink`ed only when what remains is
+ * nothing but our own header and blank lines.
+ *
+ * **A file holding NONE of our keys is not ours to touch, whatever else is in it.**
+ * The removal test used to be "what survives the strip is only blank lines and our
+ * header", which is true of a file the installer never wrote — an empty
+ * `.env.local`, or one holding a single `# Halfcycle …` note of the developer's own
+ * — so those were deleted and reported as the credential move. The presence of one
+ * of our keys is now the gate on touching the file at all.
+ *
+ * BEST-EFFORT on the rewrite: a failure (a read-only file, say) is reported, never
+ * thrown. The credential is already safe in the machine store by the time a rewrite
+ * is attempted; failing the whole install over a file we are trying to clean up
+ * would turn a successful migration into a broken one.
+ */
+export declare function migrateLegacyEnvLocal(targetRepo: string, stored: Record<string, string>): LegacyMigration;
+/**
+ * The write half of the migration: carry out a `removed` or `stripped` decision,
+ * best-effort (`failed`, never thrown). Every other decision writes nothing.
+ *
+ * **THE APPLY DECIDES AGAIN, ON PURPOSE.** The plan decides this migration against the
+ * store it EXPECTS after the credential write (`planEngagementCredential`), which is
+ * what the preview lists. The rule above is that the tree's copy goes only once a copy
+ * demonstrably lives outside it, so `applyInstallPlan` reads the store back from disk
+ * after its credential write and calls `migrateLegacyEnvLocal` again; only that
+ * decision reaches this function. A plan's prediction never deletes a credential.
+ */
+export declare function applyLegacyMigration(targetRepo: string, decided: LegacyMigration): LegacyMigration;
 /**
  * Install the bundle into a target engagement repo.
  *
@@ -1096,6 +1481,155 @@ export declare function checkDrift(targetRepoRoot: string): {
  * 11. Whether git ignores any of it — read, never changed (`setup-travel-warning`)
  */
 export declare function install(options: InstallOptions): Promise<InstallResult>;
+/**
+ * Every decision the installer's plan takes, in write order. Built by `planInstall`
+ * (`install-plan.ts`) from the planning functions below, applied by
+ * `applyInstallPlan`, and turned into the report and the install record by
+ * `accountInstall` — the same function for the plan's prediction and the apply's
+ * result, so the two cannot list different paths.
+ *
+ * `engagementId` absent is a PREVIEW: the service's answer (the project id, the
+ * credential, the method version) is still to come, so the pin, the server entry and
+ * the install record are `pending`, and such steps cannot be applied.
+ */
+export interface InstallSteps {
+    readonly targetRepo: string;
+    readonly version: string;
+    readonly engagementId: string | undefined;
+    readonly engagementType: EngagementType | undefined;
+    readonly credential: DeviceCredential | undefined;
+    readonly home: string | undefined;
+    readonly writeSet: ClosedWriteSet;
+    readonly previous: InstallManifest | null;
+    /** The write set's directories already there BEFORE anything is written. */
+    readonly dirsBefore: ReadonlySet<string>;
+    readonly commands: readonly PlannedCommand[];
+    readonly vendored: PlannedFile;
+    readonly settings: PlannedSettings;
+    readonly hooks: readonly PlannedFile[];
+    readonly ciStanza: RetiredFileRemoval;
+    readonly mcp: PlannedMcp;
+    /** The retired connection-headers helper; `null` when no server entry is written. */
+    readonly mcpHelper: RetiredFileRemoval | null;
+    readonly gitignore: PlannedMerge;
+    readonly gitattributes: PlannedMerge;
+    readonly identity: PlannedProjectIdentity;
+    /** `null` when no credential is supplied (nothing is written outside the folder). */
+    readonly credentialWrite: {
+        readonly outcome: CopyOutcome;
+        readonly existed: boolean;
+        readonly path: string;
+    } | null;
+    /** The legacy migration as PLANNED; the apply decides it again (see `applyLegacyMigration`). */
+    readonly legacy: LegacyMigration;
+    /** `null` while the project id is pending (a preview). */
+    readonly pin: PlannedFile | null;
+    readonly crew: PlannedFile;
+    readonly scan: {
+        readonly text: string | null;
+    };
+}
+/** The `.claude/settings.json` merge as planned. */
+export interface PlannedSettings {
+    readonly file: PlannedFile;
+    readonly preexisted: boolean;
+    readonly existing: ClaudeSettings;
+    readonly generated: ClaudeSettings;
+    readonly merged: ClaudeSettings;
+    readonly retiredOurs: readonly string[];
+}
+/** The `.mcp.json` server entry as planned. */
+export type PlannedMcp = {
+    readonly kind: 'write';
+    readonly existing: string | null;
+    readonly text: string;
+    readonly outcome: 'written' | 'merged' | 'skipped';
+} | {
+    readonly kind: 'none';
+    readonly existing: string | null;
+} | {
+    readonly kind: 'pending';
+    readonly existing: string | null;
+};
+/** The plugin's version and the command stubs it declares, decided against this folder. */
+export declare function planCommandStubs(targetRepo: string, previous: InstallManifest | null, writeSet: ClosedWriteSet): {
+    version: string;
+    commands: PlannedCommand[];
+};
+/** The install record an earlier install left here, or `null`. Reads only. */
+export { readPreviousManifest };
+/**
+ * 4. The vendored guard binary — the SELF-CONTAINED esbuild output at
+ * `.halfcycle/bin/bin.bundle.mjs`, owned BY PATH (T-08 walk, F-2): collision-safety froze
+ * it at whichever build first landed. It is ~600 kB with no header this package
+ * controls, so evidence-based ownership is not available here — a constraint, not a choice.
+ */
+export declare function planVendoredBinary(targetRepo: string): PlannedFile;
+/**
+ * 5. `.claude/settings.json` — MERGED, never replaced (criterion 4): every developer key
+ * kept, Halfcycle's hook entries upserted by identity. An unparseable file throws
+ * `SettingsParseRefused` with the same sentence the create arm prints (T-16, #1567).
+ * The retired deny rules this install's own record says Halfcycle added are taken out
+ * once; the status line is offered only when none is set elsewhere (`builds-paced-to-plan`
+ * AC7), those other files read and never written.
+ */
+export declare function planSettings(targetRepo: string, previous: InstallManifest | null, home: string | undefined, env: NodeJS.ProcessEnv | undefined): PlannedSettings;
+/**
+ * EVERY GENERATED HOOK SCRIPT, decided through `decideOwnedGenerated` — the criterion-5
+ * rule (#1103; G-02, #1065): a file carrying OUR generated header prefix on its header
+ * line is replaced, one that does not is `collided`. The freeze collision-safety caused
+ * was walked, not inferred (#1103).
+ */
+export declare function planHookScripts(targetRepo: string): PlannedFile[];
+/**
+ * 6b. The remote MCP registration (`.mcp.json`, T-11) — merged with the developer's own
+ * servers, the credential carried BY REFERENCE only (`MCP_HEADERS_HELPER_COMMAND`).
+ * Written ONLY when the MCP origin is known (T-24): no credential is `none`, and a
+ * preview, whose credential is still to come, is `pending`.
+ */
+export declare function planMcpRegistration(targetRepo: string, credential: DeviceCredential | 'pending' | undefined): PlannedMcp;
+/** The write half of the server entry, through `writeAllowlisted`. */
+export declare function putPlannedMcp(targetRepo: string, planned: PlannedMcp): void;
+/** 8b. The crew roster, owned by path (see `writeCrewRoster`). */
+export declare function planCrewRoster(targetRepo: string): PlannedFile;
+/** 10. The install record, owned by path, decided once its bytes are known. */
+export declare function planInstallRecord(targetRepo: string, text: string): PlannedFile;
+export { writeBundlePin, planBundlePin, writeEngagementCredential, findNotShared };
+/**
+ * What actually happened at the apply, for the steps whose write can fail without
+ * throwing (or, for the legacy migration, is decided again against the store read back
+ * from disk). For the plan's own prediction these are the planned outcomes.
+ */
+export interface InstallOutcomes {
+    readonly ciStanza: RetiredFileRemoval;
+    readonly mcpHelper: RetiredFileRemoval | null;
+    readonly gitignore: CopyOutcome | 'failed';
+    readonly gitignoreAfter: string | null;
+    readonly gitattributes: CopyOutcome | 'failed';
+    readonly gitattributesAfter: string | null;
+    readonly credential: CopyOutcome | null;
+    readonly legacy: LegacyMigration;
+    /** The bytes a path holds once the install has run (read back by the apply). */
+    readonly bytesAfter: BytesAfter;
+    /** Whether a write-set directory exists once the install has run. */
+    readonly dirExistsAfter: (dir: string) => boolean;
+    /** Whether `.halfcycle/state.json` exists once the install has run. */
+    readonly stateExistsAfter: boolean;
+}
+/**
+ * Build the install's report and its install record from the plan's steps and what
+ * happened (`InstallOutcomes`): the ONE place either is assembled, so the plan's
+ * prediction and the apply's result list the same paths by construction. Writes
+ * nothing. Requires a complete plan (no `pending` step).
+ */
+export declare function accountInstall(steps: InstallSteps, actual: InstallOutcomes): {
+    report: MutableReport;
+    installManifest: InstallManifest;
+    manifestText: string;
+};
+/** Record the install record's own write, last in the report (step 10). */
+export declare function recordInstallRecord(report: MutableReport, planned: PlannedFile): void;
+export type { MutableReport, CopyOutcome, BytesAfter };
 /** The one ignore line `.halfcycle/.gitignore` holds: the runner copy stays out of git.
  *  Exported: the monorepo uninstall (`self-build-install` AC8) removes this path by
  *  name from the same constant. */