halfcycle 0.3.23 → 0.3.25

package/dist/bin.js

@@ -30,6 +30,107 @@ var matcherSchema = z.discriminatedUnion("kind", [
   llmMatcherSchema
 ]);
 
+// ../core/dist/credential-format.js
+var HALFCYCLE_DIR_NAME = ".halfcycle";
+var ENGAGEMENTS_DIR_NAME = "engagements";
+var ENGAGEMENT_ENV_FILENAME = "env";
+var NOT_THIS_ACCOUNT_MARKER_FILENAME = "not-this-account";
+var ACCOUNT_STORE_FILENAME = "account.json";
+var ENGAGEMENT_ENV_HEADER = "# Halfcycle per-engagement credential \u2014 machine level, owner-only, never in a repository.";
+function shq(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function unquote(value) {
+  const v = value.trim();
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+    return v.slice(1, -1).split(`'\\''`).join(`'`);
+  }
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"'))
+    return v.slice(1, -1);
+  return v;
+}
+function parseEnvText(raw) {
+  const out = {};
+  for (const line of raw.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq === -1)
+      continue;
+    const key = line.slice(0, eq).replace(/^\s*export\s+/, "").trim();
+    if (key === "" || key.startsWith("#"))
+      continue;
+    out[key] = unquote(line.slice(eq + 1));
+  }
+  return out;
+}
+function reconcileEnvText(existing, values, keys) {
+  const desired = new Map(keys.map((k) => {
+    const value = values[k];
+    return [k, value === void 0 ? "" : value];
+  }));
+  const line = (k) => `${k}=${shq(desired.get(k) ?? "")}`;
+  const written = keys.filter((k) => desired.get(k) !== null);
+  if (existing === null) {
+    if (written.length === 0)
+      return "";
+    return `${ENGAGEMENT_ENV_HEADER}
+` + written.map(line).join("\n") + "\n";
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const existingLine of existing.split("\n")) {
+    const eq = existingLine.indexOf("=");
+    if (eq === -1) {
+      out.push(existingLine);
+      continue;
+    }
+    const lhs = existingLine.slice(0, eq);
+    const exported = /^\s*export\s+/.exec(lhs);
+    const prefix = exported === null ? "" : exported[0];
+    const key = lhs.slice(prefix.length).trim();
+    if (!desired.has(key)) {
+      out.push(existingLine);
+      continue;
+    }
+    seen.add(key);
+    if (desired.get(key) === null)
+      continue;
+    out.push(`${prefix}${line(key)}`);
+  }
+  const missing = written.filter((k) => !seen.has(k));
+  if (missing.length > 0) {
+    const header = existing.includes(ENGAGEMENT_ENV_HEADER) ? "" : `${ENGAGEMENT_ENV_HEADER}
+`;
+    const block = header + missing.map(line).join("\n");
+    const trailingBlank = out.length > 0 && out[out.length - 1] === "";
+    if (trailingBlank)
+      out.splice(out.length - 1, 0, block);
+    else
+      out.push(`
+${block}`);
+  }
+  let result = out.join("\n");
+  if (existing.endsWith("\n") && !result.endsWith("\n"))
+    result += "\n";
+  return result;
+}
+function normaliseOrigin(serviceUrl) {
+  return serviceUrl.trim().replace(/\/+$/, "").toLowerCase();
+}
+function parseAccountStoreText(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || typeof parsed.accounts !== "object") {
+      return { version: 1, accounts: {} };
+    }
+    return {
+      version: 1,
+      accounts: parsed.accounts ?? {}
+    };
+  } catch {
+    return { version: 1, accounts: {} };
+  }
+}
+
 // ../events/dist/result.js
 var firedGuardSchema = z2.object({
   guardId: z2.string(),
@@ -90,7 +191,7 @@ var wireErrorSchema = z2.object({
 
 // ../events/dist/telemetry.js
 import { z as z3 } from "zod";
-var utcIso8601 = z3.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z (INV-015)");
+var utcIso8601 = z3.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z");
 var guardEvalOutcomeSchema = z3.enum([
   "evaluated",
   "infra-error",
@@ -146,7 +247,7 @@ var guardEvalRunSchema = z3.object({
 
 // ../events/dist/engagement-lifecycle.js
 import { z as z4 } from "zod";
-var utcIso86012 = z4.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z (INV-015)");
+var utcIso86012 = z4.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z");
 var engagementTypeSchema = z4.enum(["client"]);
 var lifecycleStatusSchema = z4.enum(["active", "delivering", "closed"]);
 var createEngagementRequestSchema = z4.object({
@@ -275,16 +376,184 @@ var openPhaseResponseSchema = z4.object({
   decision: phaseEntryDecisionRecordSchema
 }).strict();
 
-// ../events/dist/crew.js
+// ../events/dist/state.js
 import { z as z5 } from "zod";
-var crewGroupSchema = z5.enum(["builder", "reviewer", "always-on"]);
-var crewTierSchema = z5.enum(["deep", "standard", "fast"]);
+var utcIso86013 = z5.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z");
+var STATE_RECORD_FORMAT = "halfcycle-state-record/v1";
+var stepIdSchema = z5.string().regex(/^(l[0-5](-l[0-5])?|xl)\.[a-z0-9-]+$/);
+var methodVersionSchema = z5.string().regex(/^\d+\.\d+\.\d+$/);
+var anchorPathRegex = /^(?!\/)(?!.*#)(?!method\/)(?!(.*\/)?docs\/method\/).+$/;
+var recordKindSchema = z5.enum(["artefact", "step-run", "gate", "intervention"]);
+var methodLayerSchema = z5.enum(["l0", "l1", "l2", "l3", "l3-l4", "l4", "l5", "xl"]);
+var evidenceKindSchema = z5.enum(["anchor", "diff", "repro", "question-answer", "no-op"]);
+var declarableEvidenceKindSchema = z5.enum(["anchor", "diff", "repro", "question-answer"]);
+var dispositionSchema = z5.enum([
+  "prevented",
+  "corrected-in-spec",
+  "corrected-in-scope",
+  "blocked-in-code",
+  "flagged",
+  "auto-fixed",
+  "surfaced",
+  "filed-forward"
+]);
+var mechanismSchema = z5.enum(["guard", "verdict", "served-step", "method-step"]);
+var artefactStateSchema = z5.enum(["created", "updated"]);
+var QUALIFIED_OUTCOMES = ["declined", "parked"];
+var qualifiedOutcomeSchema = z5.enum(QUALIFIED_OUTCOMES);
+function isQualifiedOutcome(outcome) {
+  return QUALIFIED_OUTCOMES.includes(outcome);
+}
+var runOutcomeSchema = z5.enum([
+  "completed",
+  "attempted-failed",
+  ...QUALIFIED_OUTCOMES
+]);
+var gateKindSchema = z5.enum(["approval", "mechanical"]);
+var gateVerdictSchema = z5.enum(["pass", "fail", ...QUALIFIED_OUTCOMES]);
+function outcomeReasonIssue(outcome, reason) {
+  if (isQualifiedOutcome(outcome) && reason === void 0) {
+    return { message: `outcomeReason is required when the outcome is '${outcome}'` };
+  }
+  if (!isQualifiedOutcome(outcome) && reason !== void 0) {
+    return {
+      message: `outcomeReason is only present on a qualified outcome (${QUALIFIED_OUTCOMES.join(" | ")})`
+    };
+  }
+  return null;
+}
+var anchorEvidenceSchema = z5.object({
+  kind: z5.literal("anchor"),
+  path: z5.string().regex(anchorPathRegex),
+  // Optional 1-based line number within the file at `path`. Present when the
+  // writer knows the exact line; omitted — never `0`, never `null` — when it
+  // does not, because a line number is not always obtainable. Absence is a
+  // valid, permanent state here, not a gap meant to be filled in later.
+  line: z5.number().optional()
+}).strict();
+var diffEvidenceSchema = z5.object({
+  kind: z5.literal("diff"),
+  ref: z5.string()
+}).strict();
+var reproEvidenceSchema = z5.object({
+  kind: z5.literal("repro"),
+  steps: z5.string().max(2e3)
+}).strict();
+var questionAnswerEvidenceSchema = z5.object({
+  kind: z5.literal("question-answer"),
+  question: z5.string().max(2e3),
+  before: z5.string().max(2e3),
+  after: z5.string().max(2e3)
+}).strict();
+var noOpEvidenceSchema = z5.object({
+  kind: z5.literal("no-op"),
+  inspected: z5.string().max(2e3),
+  unchangedBecause: z5.string().max(2e3)
+}).strict();
+var evidenceSchema = z5.discriminatedUnion("kind", [
+  anchorEvidenceSchema,
+  diffEvidenceSchema,
+  reproEvidenceSchema,
+  questionAnswerEvidenceSchema,
+  noOpEvidenceSchema
+]);
+var stateRecordEnvelopeSchema = z5.object({
+  format: z5.literal(STATE_RECORD_FORMAT),
+  recordKind: recordKindSchema,
+  recordId: z5.string().uuid(),
+  methodVersion: methodVersionSchema,
+  engagementId: z5.string(),
+  stepId: stepIdSchema,
+  // Immutable: names when the thing happened, never when a later disposition
+  // moved.
+  occurredAt: utcIso86013,
+  // Equal to `occurredAt` on first write; advances on each re-emit OF A FINDING.
+  // Carried on the shared envelope so a "when did this last change" query is
+  // kind-agnostic. Kept rather than generalised to `updatedAt` because
+  // `disposition` is the only field any re-emit may change (§5.3).
+  dispositionAt: utcIso86013,
+  evidence: evidenceSchema,
+  // Which phase of the project this record belongs to, if any. Present on
+  // records written during phase-scoped work; absent on records that run once
+  // for the whole project rather than per phase. Absence is meaningful on its
+  // own — it is never replaced with a placeholder value, and it is read as
+  // "satisfies any phase", not as "unknown".
+  phase: z5.string().optional()
+});
+var artefactRefSchema = z5.object({
+  name: z5.string(),
+  parent: z5.string()
+}).strict();
+var artefactRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z5.literal("artefact"),
+  artefactRef: artefactRefSchema,
+  // Some layer wrote it, by construction — an empty array is not a legitimate
+  // state, so the schema says so.
+  writtenByLayers: z5.array(methodLayerSchema).min(1),
+  state: artefactStateSchema
+}).strict();
+var stepRunRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z5.literal("step-run"),
+  runOutcome: runOutcomeSchema,
+  failureReason: z5.string().optional(),
+  outcomeReason: z5.string().max(2e3).optional()
+}).strict().superRefine((rec, ctx) => {
+  if (rec.runOutcome === "attempted-failed" && rec.failureReason === void 0) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      path: ["failureReason"],
+      message: "failureReason is required when runOutcome is 'attempted-failed'"
+    });
+  }
+  if (rec.runOutcome !== "attempted-failed" && rec.failureReason !== void 0) {
+    ctx.addIssue({
+      code: z5.ZodIssueCode.custom,
+      path: ["failureReason"],
+      message: "failureReason is only present when runOutcome is 'attempted-failed'"
+    });
+  }
+  const issue = outcomeReasonIssue(rec.runOutcome, rec.outcomeReason);
+  if (issue) {
+    ctx.addIssue({ code: z5.ZodIssueCode.custom, path: ["outcomeReason"], ...issue });
+  }
+});
+var gateRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z5.literal("gate"),
+  gateKind: gateKindSchema,
+  verdict: gateVerdictSchema,
+  actor: z5.string(),
+  outcomeReason: z5.string().max(2e3).optional()
+}).strict().superRefine((rec, ctx) => {
+  const issue = outcomeReasonIssue(rec.verdict, rec.outcomeReason);
+  if (issue) {
+    ctx.addIssue({ code: z5.ZodIssueCode.custom, path: ["outcomeReason"], ...issue });
+  }
+});
+var interventionRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z5.literal("intervention"),
+  layer: methodLayerSchema,
+  mechanism: mechanismSchema,
+  severity: severitySchema,
+  disposition: dispositionSchema,
+  summary: z5.string().max(2e3)
+}).strict();
+var stateRecordSchema = z5.discriminatedUnion("recordKind", [
+  artefactRecordSchema,
+  stepRunRecordSchema,
+  gateRecordSchema,
+  interventionRecordSchema
+]);
+
+// ../events/dist/crew.js
+import { z as z6 } from "zod";
+var crewGroupSchema = z6.enum(["builder", "reviewer", "always-on"]);
+var crewTierSchema = z6.enum(["deep", "standard", "fast"]);
 var CREW_DISCIPLINE_MAX = 64;
-var crewFaceHeadSchema = z5.enum(["sq", "sqr", "rnd", "dome", "hex"]);
-var crewFaceAntennaSchema = z5.enum(["none", "stalk", "twin", "dish"]);
-var crewFaceEyesSchema = z5.enum(["dots", "bars", "visor", "cyclops"]);
-var crewFaceMouthSchema = z5.enum(["line", "grid", "dots", "wave"]);
-var crewFaceSchema = z5.object({
+var crewFaceHeadSchema = z6.enum(["sq", "sqr", "rnd", "dome", "hex"]);
+var crewFaceAntennaSchema = z6.enum(["none", "stalk", "twin", "dish"]);
+var crewFaceEyesSchema = z6.enum(["dots", "bars", "visor", "cyclops"]);
+var crewFaceMouthSchema = z6.enum(["line", "grid", "dots", "wave"]);
+var crewFaceSchema = z6.object({
   // The outline of the head. Members who do the same kind of work share one, so a
   // team is recognisable before any name is read.
   head: crewFaceHeadSchema,
@@ -295,17 +564,17 @@ var crewFaceSchema = z5.object({
   // The mouth.
   mouth: crewFaceMouthSchema,
   // Whether this member is drawn with ears.
-  ears: z5.boolean()
+  ears: z6.boolean()
 }).strict();
-var crewMemberSchema = z5.object({
+var crewMemberSchema = z6.object({
   // The agent's name. The same twenty-one on every project, so a name is a
   // vocabulary a returning client already knows.
-  callsign: z5.string().min(1).max(32),
+  callsign: z6.string().min(1).max(32),
   // Which of the three headings this member reads under.
   group: crewGroupSchema,
   // The kind of work this member takes. A task names a discipline, and only
   // agents holding it can be dispatched to it.
-  discipline: z5.string().min(1).max(CREW_DISCIPLINE_MAX),
+  discipline: z6.string().min(1).max(CREW_DISCIPLINE_MAX),
   // How much thinking this member brings. There is no field naming the supplier
   // behind it, on this shape or on any other.
   tier: crewTierSchema,
@@ -470,8 +739,8 @@ var CREW_ROSTER_SIZE = CREW_ROSTER.length;
 var CREW_CALLSIGNS = CREW_ROSTER.map((member) => member.callsign);
 
 // ../events/dist/device-auth.js
-import { z as z6 } from "zod";
-var utcIso86013 = z6.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z (INV-015)");
+import { z as z7 } from "zod";
+var utcIso86014 = z7.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z");
 var DEVICE_AUTH_STATUS = {
   /** The poll: minted, nobody has acted yet. Keep polling. 200. */
   PENDING: "pending",
@@ -497,7 +766,7 @@ var DEVICE_AUTH_STATUS = {
   ALREADY_DECIDED: "already-decided",
   /**
    * Confirm: an approval named a signed-in identity whose account has not accepted
-   * the terms of service and privacy policy currently in force (T-18, #588). 400.
+   * the terms of service and privacy policy currently in force. 400.
    *
    * NOT BOUND TO THE DEVICE CODE. Unlike every other refusal in this const, this one
    * says nothing about the code itself — the code is still `pending` after this
@@ -512,25 +781,25 @@ var DEVICE_POLL_REFUSALS = [
   DEVICE_AUTH_STATUS.EXPIRED,
   DEVICE_AUTH_STATUS.UNKNOWN
 ];
-var deviceAuthStartResponseSchema = z6.object({
-  deviceCode: z6.string().min(1),
-  userCode: z6.string().min(1),
-  verificationUrl: z6.string().min(1),
-  expiresAt: utcIso86013,
-  pollIntervalMs: z6.number().int().positive()
+var deviceAuthStartResponseSchema = z7.object({
+  deviceCode: z7.string().min(1),
+  userCode: z7.string().min(1),
+  verificationUrl: z7.string().min(1),
+  expiresAt: utcIso86014,
+  pollIntervalMs: z7.number().int().positive()
 }).strict();
-var devicePollPendingSchema = z6.object({
-  status: z6.literal(DEVICE_AUTH_STATUS.PENDING),
-  pollIntervalMs: z6.number().int().positive()
+var devicePollPendingSchema = z7.object({
+  status: z7.literal(DEVICE_AUTH_STATUS.PENDING),
+  pollIntervalMs: z7.number().int().positive()
 }).strict();
-var devicePollApprovedSchema = z6.object({
-  status: z6.literal(DEVICE_AUTH_STATUS.APPROVED),
-  accountId: z6.string().min(1),
-  credential: z6.string().min(1),
-  expiresAt: utcIso86013
+var devicePollApprovedSchema = z7.object({
+  status: z7.literal(DEVICE_AUTH_STATUS.APPROVED),
+  accountId: z7.string().min(1),
+  credential: z7.string().min(1),
+  expiresAt: utcIso86014
 }).strict();
-var deviceAuthRefusalSchema = z6.object({
-  status: z6.enum([
+var deviceAuthRefusalSchema = z7.object({
+  status: z7.enum([
     DEVICE_AUTH_STATUS.DECLINED,
     DEVICE_AUTH_STATUS.EXPIRED,
     DEVICE_AUTH_STATUS.UNKNOWN,
@@ -541,25 +810,25 @@ var deviceAuthRefusalSchema = z6.object({
     DEVICE_AUTH_STATUS.ALREADY_DECIDED,
     DEVICE_AUTH_STATUS.TERMS_REQUIRED
   ]),
-  message: z6.string().min(1)
+  message: z7.string().min(1)
 }).strict();
-var devicePollResponseSchema = z6.union([
+var devicePollResponseSchema = z7.union([
   devicePollPendingSchema,
   devicePollApprovedSchema,
   deviceAuthRefusalSchema
 ]);
-var deviceConfirmRequestSchema = z6.object({
-  userCode: z6.string().min(1),
-  decision: z6.enum(["approve", "decline"]),
-  externalAuthId: z6.string().min(1).optional(),
-  email: z6.string().optional(),
-  acceptTerms: z6.boolean().optional()
+var deviceConfirmRequestSchema = z7.object({
+  userCode: z7.string().min(1),
+  decision: z7.enum(["approve", "decline"]),
+  externalAuthId: z7.string().min(1).optional(),
+  email: z7.string().optional(),
+  acceptTerms: z7.boolean().optional()
 }).strict();
-var deviceConfirmRecordedSchema = z6.object({
-  status: z6.literal(DEVICE_AUTH_STATUS.RECORDED),
-  accountId: z6.string().min(1).optional()
+var deviceConfirmRecordedSchema = z7.object({
+  status: z7.literal(DEVICE_AUTH_STATUS.RECORDED),
+  accountId: z7.string().min(1).optional()
 }).strict();
-var deviceConfirmResponseSchema = z6.union([
+var deviceConfirmResponseSchema = z7.union([
   deviceConfirmRecordedSchema,
   deviceAuthRefusalSchema
 ]);
@@ -588,25 +857,25 @@ function loopbackVerificationUrl(verificationUrl, target) {
 }
 
 // ../events/dist/join-refusal.js
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var NOT_THIS_ACCOUNT_REASON = "not-this-account";
 var JOIN_REFUSAL_STATUS = 403;
-var notThisAccountRefusalSchema = z7.object({
-  statusCode: z7.literal(JOIN_REFUSAL_STATUS),
-  error: z7.string(),
-  message: z7.string(),
-  reason: z7.literal(NOT_THIS_ACCOUNT_REASON)
+var notThisAccountRefusalSchema = z8.object({
+  statusCode: z8.literal(JOIN_REFUSAL_STATUS),
+  error: z8.string(),
+  message: z8.string(),
+  reason: z8.literal(NOT_THIS_ACCOUNT_REASON)
 }).strict();
-var joinRefusalSchema = z7.union([notThisAccountRefusalSchema, wireErrorSchema]);
+var joinRefusalSchema = z8.union([notThisAccountRefusalSchema, wireErrorSchema]);
 function isNotThisAccountRefusal(body) {
   return typeof body === "object" && body !== null && body.reason === NOT_THIS_ACCOUNT_REASON;
 }
 
 // ../events/dist/account-identity.js
-import { z as z8 } from "zod";
-var accountIdentitySchema = z8.object({
-  accountId: z8.string().min(1),
-  email: z8.string().min(1).optional()
+import { z as z9 } from "zod";
+var accountIdentitySchema = z9.object({
+  accountId: z9.string().min(1),
+  email: z9.string().min(1).optional()
 }).strict();
 function safeParseAccountIdentity(payload) {
   return accountIdentitySchema.safeParse(payload);
@@ -673,6 +942,21 @@ function describeIdentity(identity) {
   return `(a ${typeof identity})`;
 }
 
+// ../events/dist/credential-wire.js
+import { z as z10 } from "zod";
+var engagementCredentialResponseSchema = z10.object({
+  engagementId: z10.string(),
+  sessionToken: z10.string(),
+  mcpUrl: z10.string(),
+  guardUrl: z10.string(),
+  controlTelemetryUrl: z10.string()
+}).strict();
+var ciTokenExchangeResponseSchema = z10.object({
+  token: z10.string(),
+  expiresAt: utcIso86013,
+  engagementId: z10.string()
+}).strict();
+
 // dist/engagement-credential.js
 import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { platform as platform2 } from "node:os";
@@ -683,27 +967,14 @@ import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 function halfcycleHome(home) {
-  return join(home ?? homedir(), ".halfcycle");
+  return join(home ?? homedir(), HALFCYCLE_DIR_NAME);
 }
 function accountStorePath(home) {
-  return join(halfcycleHome(home), "account.json");
-}
-function normaliseOrigin(serviceUrl) {
-  return serviceUrl.trim().replace(/\/+$/, "").toLowerCase();
+  return join(halfcycleHome(home), ACCOUNT_STORE_FILENAME);
 }
 function readStore(home) {
-  let raw;
   try {
-    raw = readFileSync(accountStorePath(home), "utf-8");
-  } catch {
-    return { version: 1, accounts: {} };
-  }
-  try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || typeof parsed.accounts !== "object") {
-      return { version: 1, accounts: {} };
-    }
-    return { version: 1, accounts: parsed.accounts ?? {} };
+    return parseAccountStoreText(readFileSync(accountStorePath(home), "utf-8"));
   } catch {
     return { version: 1, accounts: {} };
   }
@@ -749,8 +1020,9 @@ function forgetStoredCredential(serviceUrl, home) {
 }
 
 // dist/engagement-credential.js
-var ENGAGEMENTS_DIR = "engagements";
-var ENV_FILENAME = "env";
+var ENGAGEMENTS_DIR = ENGAGEMENTS_DIR_NAME;
+var ENV_FILENAME = ENGAGEMENT_ENV_FILENAME;
+var HALFCYCLE_DIR = HALFCYCLE_DIR_NAME;
 var PIN_ENGAGEMENT_ID_FIELD = "engagementId";
 function engagementStateDir(engagementId, home) {
   return join2(halfcycleHome(home), ENGAGEMENTS_DIR, engagementId);
@@ -758,7 +1030,6 @@ function engagementStateDir(engagementId, home) {
 function engagementEnvPath(engagementId, home) {
   return join2(engagementStateDir(engagementId, home), ENV_FILENAME);
 }
-var NOT_THIS_ACCOUNT_MARKER_FILENAME = "not-this-account";
 function notThisAccountMarkerPath(engagementId, home) {
   return join2(engagementStateDir(engagementId, home), NOT_THIS_ACCOUNT_MARKER_FILENAME);
 }
@@ -785,82 +1056,8 @@ var ENGAGEMENT_ENV_KEYS = [
   "CONTROL_TELEMETRY_URL"
 ];
 var PHASE_STAMP_ENV_KEY = "HALFCYCLE_PHASE";
-var ENV_HEADER = "# Halfcycle per-engagement credential \u2014 machine level, owner-only, never in a repository.";
-function shq(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-function unquote(value) {
-  const v = value.trim();
-  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
-    return v.slice(1, -1).split(`'\\''`).join(`'`);
-  }
-  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"'))
-    return v.slice(1, -1);
-  return v;
-}
-function parseEnvText(raw) {
-  const out = {};
-  for (const line of raw.split("\n")) {
-    const eq = line.indexOf("=");
-    if (eq === -1)
-      continue;
-    const key = line.slice(0, eq).replace(/^\s*export\s+/, "").trim();
-    if (key === "" || key.startsWith("#"))
-      continue;
-    out[key] = unquote(line.slice(eq + 1));
-  }
-  return out;
-}
-function reconcileEnvText(existing, values, keys = ENGAGEMENT_ENV_KEYS) {
-  const desired = new Map(keys.map((k) => {
-    const value = values[k];
-    return [k, value === void 0 ? "" : value];
-  }));
-  const line = (k) => `${k}=${shq(desired.get(k) ?? "")}`;
-  const written = keys.filter((k) => desired.get(k) !== null);
-  if (existing === null) {
-    if (written.length === 0)
-      return "";
-    return `${ENV_HEADER}
-` + written.map(line).join("\n") + "\n";
-  }
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
-  for (const existingLine of existing.split("\n")) {
-    const eq = existingLine.indexOf("=");
-    if (eq === -1) {
-      out.push(existingLine);
-      continue;
-    }
-    const lhs = existingLine.slice(0, eq);
-    const exported = /^\s*export\s+/.exec(lhs);
-    const prefix = exported === null ? "" : exported[0];
-    const key = lhs.slice(prefix.length).trim();
-    if (!desired.has(key)) {
-      out.push(existingLine);
-      continue;
-    }
-    seen.add(key);
-    if (desired.get(key) === null)
-      continue;
-    out.push(`${prefix}${line(key)}`);
-  }
-  const missing = written.filter((k) => !seen.has(k));
-  if (missing.length > 0) {
-    const header = existing.includes(ENV_HEADER) ? "" : `${ENV_HEADER}
-`;
-    const block = header + missing.map(line).join("\n");
-    const trailingBlank = out.length > 0 && out[out.length - 1] === "";
-    if (trailingBlank)
-      out.splice(out.length - 1, 0, block);
-    else
-      out.push(`
-${block}`);
-  }
-  let result = out.join("\n");
-  if (existing.endsWith("\n") && !result.endsWith("\n"))
-    result += "\n";
-  return result;
+function reconcileEnvText2(existing, values, keys = ENGAGEMENT_ENV_KEYS) {
+  return reconcileEnvText(existing, values, keys);
 }
 function readEngagementEnv(engagementId, home) {
   try {
@@ -878,7 +1075,7 @@ function writeEngagementEnv(engagementId, values, home, keys = ENGAGEMENT_ENV_KE
   } catch {
     existing = null;
   }
-  const reconciled = reconcileEnvText(existing, values, keys);
+  const reconciled = reconcileEnvText2(existing, values, keys);
   if (existing === null && reconciled === "")
     return "skipped";
   mkdirSync2(dir, { recursive: true, mode: 448 });
@@ -904,7 +1101,7 @@ function applyOwnerOnly(path, dir) {
 function engagementResolutionShell() {
   return `# --- Halfcycle credential resolution (generated; do not edit) ----------------
 # THE CREDENTIAL IS NOT IN THIS REPOSITORY. It lives at
-#   $HOME/.halfcycle/${ENGAGEMENTS_DIR}/<engagement-id>/${ENV_FILENAME}
+#   $HOME/${HALFCYCLE_DIR}/${ENGAGEMENTS_DIR}/<engagement-id>/${ENV_FILENAME}
 # written owner-only by \`npx halfcycle\`. What this repository holds is the
 # engagement id, in the committed .halfcycle/bundle.json. So: read the id out of
 # the pin, then name the file. There is no jq here and node is not dependable on a
@@ -935,10 +1132,10 @@ halfcycle_env_file() {
     HALFCYCLE_ENV_PROBLEM="no-home"
     return 1
   fi
-  if [ -f "$HOME/.halfcycle/${ENGAGEMENTS_DIR}/$hc_id/${NOT_THIS_ACCOUNT_MARKER_FILENAME}" ]; then
+  if [ -f "$HOME/${HALFCYCLE_DIR}/${ENGAGEMENTS_DIR}/$hc_id/${NOT_THIS_ACCOUNT_MARKER_FILENAME}" ]; then
     HALFCYCLE_ENV_NOT_THIS_ACCOUNT=1
   fi
-  hc_env="$HOME/.halfcycle/${ENGAGEMENTS_DIR}/$hc_id/${ENV_FILENAME}"
+  hc_env="$HOME/${HALFCYCLE_DIR}/${ENGAGEMENTS_DIR}/$hc_id/${ENV_FILENAME}"
   if [ ! -f "$hc_env" ]; then
     HALFCYCLE_ENV_PROBLEM="no-credential"
     return 1
@@ -1129,7 +1326,7 @@ function resolveVendoredBinary() {
     if (existsSync3(candidate))
       return candidate;
   }
-  throw new Error(`[bundle install] Cannot find the self-contained guard binary bin.bundle.mjs. Run the runner's "bundle" script (pnpm --filter @halfcycle/runner run build) so the vendored artefact exists before installing. Looked in: ${candidates.join(", ")}.`);
+  throw new Error(`[bundle install] Cannot find the self-contained guard binary bin.bundle.mjs. This copy of the halfcycle package is incomplete \u2014 reinstall it, or rebuild it if you are working on it. Looked in: ${candidates.join(", ")}.`);
 }
 var WRITE_ALLOWLIST = [
   ".claude/commands",
@@ -1278,6 +1475,15 @@ function generateSettingsJson() {
               timeout: 5
             }
           ]
+        },
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "bash ./.claude/hooks/guard-runner.sh refresh-credential",
+              timeout: 10
+            }
+          ]
         }
       ],
       UserPromptSubmit: [
@@ -1347,9 +1553,9 @@ function generateGuardRunnerWrapper() {
 ${GENERATED_GUARD_RUNNER_HEADER} the Halfcycle installer.
 #
 # Loads this engagement's credentials so the guard runner has its GUARD_SERVICE_*
-# values when Claude Code fires PostToolUse / Stop / SubagentStop, then exec's the
-# SELF-CONTAINED binary vendored at ${VENDORED_BIN_REL} \u2014 a path inside this
-# project, so the hook resolves in any checkout of it.
+# values when Claude Code fires SessionStart / PostToolUse / Stop / SubagentStop,
+# then exec's the SELF-CONTAINED binary vendored at ${VENDORED_BIN_REL} \u2014 a path
+# inside this project, so the hook resolves in any checkout of it.
 #
 # The runner itself reads only process.env, so env loading lives here in the hook
 # wiring rather than inside the binary.
@@ -1364,6 +1570,16 @@ ${engagementResolutionShell()}
 # the runner say what it found \u2014 its never-configured branch is loud and non-zero
 # on purpose, and a wrapper that exited quietly here would hide it.
 if halfcycle_env_file "$PROJECT_DIR"; then
+  # EXPORTED, NOT MERELY SET \u2014 one word, and without it a whole feature is off.
+  # \`set -a\` exports what is assigned AFTER it, and the resolution above assigned
+  # this variable BEFORE it, so the exec'd binary would never see the name of the
+  # file these credentials came from. It needs that name: when the service says
+  # this engagement's credential has timed out, the binary renews it by rewriting
+  # that file. With nothing naming the file it renews nothing \u2014 and it says
+  # nothing and exits 0 while doing so, because there is no session in which that
+  # silence is wrong on its own. So a wrapper missing this line looks perfectly
+  # healthy at every session start and renews nothing, forever.
+  export HALFCYCLE_ENV_FILE
   set -a
   . "$HALFCYCLE_ENV_FILE"
   set +a
@@ -1550,19 +1766,36 @@ function generateCiStanza() {
 # .halfcycle/bin/, so it works in a Python or Go repository as well as a Node
 # one \u2014 the only prerequisite is Node 20 to run the bundled binary.
 #
+# THERE IS NOTHING TO STORE. No token in your repository's secrets, no project id
+# to look up, and no address to set. The \`permissions\` block below is the whole
+# configuration: it lets the job ask GitHub for a short-lived signed token naming
+# the repository it is running in, and Halfcycle trusts the name GitHub signs
+# rather than anything the job says about itself. That token is traded for a
+# credential that lives for minutes, and nothing is kept at either end.
+#
+# BOTH PERMISSION LINES, NOT JUST THE SECOND. Declaring any permission
+# replaces the defaults rather than adding to them, so a block naming only
+# \`id-token\` takes read access away from the checkout step and a private
+# repository stops checking out before the guard is reached. If your workflow
+# already has a \`permissions\` block, add \`id-token: write\` to it and leave the
+# rest alone.
+#
+# ONE THING TO DO FIRST, ONCE, ON YOUR OWN MACHINE. In this project, run
+#
+#     npx halfcycle ci bind <owner>/<repo>
+#
+# naming this repository as GitHub spells it (for example acme/widgets). That
+# tells Halfcycle this project's CI runs from that repository, and it is the only
+# thing that makes a run mean anything: without it, Halfcycle has a signed
+# statement of which repository the job is in and no idea whose project that is.
+# The check says exactly that, and names the command, if you skip it.
+#
 # THERE IS NO ADDRESS TO CONFIGURE ANYWHERE IN HALFCYCLE. Every service this
 # product talks to has one address, the same for every user, and it ships in the
 # tools you already have: the installer, the guard hook and the binary this job
 # runs each know where to go. If something tells you to set a Halfcycle URL, it is
 # out of date.
 #
-# AND THERE IS NOTHING TO SET ON YOUR OWN MACHINE EITHER. \`npx halfcycle\` wrote
-# this engagement's credential to $HOME/.halfcycle, owner-only, outside every
-# checkout, and the guard hook reads it from there. A CI job is the one place that
-# store cannot be reached \u2014 no browser, no per-user home \u2014 which is why the two
-# names below exist at all, and why they are the only two: a credential, and the id
-# of your own engagement.
-#
 # WHICH BRANCH MODEL THIS ASSUMES: none. It works on pull-request branches AND on
 # commits pushed straight to the default branch, which is the shape most
 # Halfcycle engagements settle on. \`fetch-depth\` is what makes that true: the
@@ -1573,6 +1806,9 @@ function generateCiStanza() {
 #
 # halfcycle-guard-ci:
 #   runs-on: ubuntu-latest
+#   permissions:
+#     contents: read
+#     id-token: write
 #   steps:
 #     - uses: actions/checkout@v4
 #       with:
@@ -1584,20 +1820,15 @@ function generateCiStanza() {
 #       with:
 #         node-version: '20'
 #     - name: Halfcycle guard CI check
-#       env:
-#         # TWO SECRETS, AND THEY ARE THE TWO THAT ARE YOURS: the engagement's
-#         # token and its id. Both were printed by the installer that generated
-#         # this file. There is no address to configure \u2014 the guard service this
-#         # job talks to ships inside the binary below.
-#         GUARD_SERVICE_TOKEN: \${{ secrets.GUARD_SERVICE_TOKEN }}
-#         GUARD_ENGAGEMENT_ID: \${{ secrets.GUARD_ENGAGEMENT_ID }}
+#       # No env block, on purpose: this step holds no secret. The permissions
+#       # above are what authenticate it.
 #       run: node ./.halfcycle/bin/bin.bundle.mjs ci
 #
 # The job prints the diff base it used and how many files it evaluated, on every
 # run. If that line says 0 files on a commit that changed something, the base is
-# wrong \u2014 set HALFCYCLE_DIFF_BASE in the env block OF YOUR COPY, beside the two
-# secrets, to name it explicitly (on a GitHub push event, \${{ github.event.before }}
-# is the right value).
+# wrong \u2014 set HALFCYCLE_DIFF_BASE in an env block OF YOUR COPY of the check step,
+# to name it explicitly (on a GitHub push event, \${{ github.event.before }} is the
+# right value).
 #
 # EDIT YOUR COPY, NOT THIS FILE. This one is regenerated by the installer and your
 # changes to it would be replaced the next time you run \`npx halfcycle\`. It is
@@ -2213,6 +2444,7 @@ var SIGN_IN_TIMEOUT_MESSAGE = "Sign-in timed out: the Halfcycle service stopped
 var SIGN_IN_NON_INTERACTIVE_MESSAGE = "Halfcycle needs a signed-in account and this looks like a non-interactive run (CI is set), so there is no browser to sign in with. Set HALFCYCLE_TOKEN in the environment to a Halfcycle credential and run this again. Nothing was created.";
 var DEADLINE_SLACK_INTERVALS = 1;
 var STILL_WAITING_MS = 15e3;
+var DEFAULT_SIGN_IN_REASON = "create an engagement";
 function defaultWrite(text) {
   process.stdout.write(text);
 }
@@ -2402,7 +2634,7 @@ async function signIn(serviceUrl, deps = {}) {
   if (isNonInteractive(env)) {
     throw new SignInRefused(SIGN_IN_TIMED_OUT, SIGN_IN_NON_INTERACTIVE_MESSAGE);
   }
-  write(`[halfcycle] Halfcycle needs an account before it can create an engagement \u2014 signing you in through your browser.
+  write(`[halfcycle] Halfcycle needs an account before it can ${deps.reason ?? DEFAULT_SIGN_IN_REASON} \u2014 signing you in through your browser.
 `);
   const bind = await bindLoopback(env);
   let closed = false;
@@ -2559,6 +2791,12 @@ async function joinEngagement(baseUrl, engagementId, credential) {
     route: "POST /engagements/:engagementId/join"
   });
 }
+function withDeclaredTelemetryKey(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+    return null;
+  const obj = raw;
+  return "controlTelemetryUrl" in obj ? obj : { ...obj, controlTelemetryUrl: "" };
+}
 async function requestEngagementValues(url, requestBody, credential, shape) {
   const bearer = credential?.trim();
   let res;
@@ -2583,7 +2821,9 @@ async function requestEngagementValues(url, requestBody, credential, shape) {
     const wrongOrigin = res.status === 404 ? `That address answered, but it does not serve ${shape.route} \u2014 so it is not the Halfcycle service. ` : "";
     throw new Error(`[bundle install] ${shape.action} failed: ${url} returned ${res.status}. ${wrongOrigin}${detail ? `Response: ${detail.slice(0, 300)}. ` : ""}${shape.nothingHappened}. ` + CONTROL_ORIGIN_HINT);
   }
-  const body = await res.json().catch(() => null);
+  const candidate = withDeclaredTelemetryKey(await res.json().catch(() => null));
+  const declared = engagementCredentialResponseSchema.safeParse(candidate);
+  const body = declared.success ? declared.data : candidate;
   if (!body || typeof body.engagementId !== "string" || typeof body.sessionToken !== "string") {
     throw new Error(`[bundle install] ${shape.action} response from ${url} did not carry {engagementId, sessionToken}. ${shape.nothingHappened}. ` + CONTROL_ORIGIN_HINT);
   }
@@ -2602,6 +2842,16 @@ async function requestEngagementValues(url, requestBody, credential, shape) {
     throw new Error(`[bundle install] The Halfcycle service at ${url} created an engagement but did not say where its guard service lives (no guardUrl on the response). Without that address the install would wire a guard hook that evaluates nothing, so nothing was written. Either that service is older than this installer, or ${url} is not a Halfcycle service.`);
   }
   const controlTelemetryUrl = typeof body.controlTelemetryUrl === "string" && body.controlTelemetryUrl.trim() !== "" ? body.controlTelemetryUrl.trim().replace(/\/+$/, "") : void 0;
+  if (!declared.success) {
+    const fields = declared.error.issues.map((issue) => {
+      const unrecognised = issue.keys;
+      if (unrecognised && unrecognised.length > 0) {
+        return `unexpected: ${unrecognised.map(String).join(", ")}`;
+      }
+      return issue.path.length > 0 ? issue.path.map(String).join(".") : "(the body itself)";
+    }).join(", ");
+    throw new Error(`[bundle install] ${shape.action} response from ${url} is not the credential response this CLI is built to read (${fields}). ${shape.nothingHappened}. Either that service is a different version from this installer, or ${url} is not a Halfcycle service.`);
+  }
   return {
     engagementId: body.engagementId,
     sessionToken: body.sessionToken,
@@ -2940,7 +3190,8 @@ function currentEnvironment(quiet2) {
 // dist/confirm-identity.js
 var IDENTITY_TIMEOUT_MS = 5e3;
 var IDENTITY_DECLINED = "identity-declined";
-async function describeAccount(serviceUrl, credential, fetchImpl = fetch) {
+var CREDENTIAL_REFUSED = 401;
+async function askAccount(serviceUrl, credential, fetchImpl = fetch) {
   const url = `${serviceUrl.replace(/\/+$/, "")}/account`;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), IDENTITY_TIMEOUT_MS);
@@ -2950,15 +3201,18 @@ async function describeAccount(serviceUrl, credential, fetchImpl = fetch) {
       signal: controller.signal
     });
     if (!res.ok)
-      return void 0;
+      return { identity: void 0, refused: res.status === CREDENTIAL_REFUSED };
     const parsed = safeParseAccountIdentity(await res.json());
-    return parsed.success ? parsed.data : void 0;
+    return { identity: parsed.success ? parsed.data : void 0, refused: false };
   } catch {
-    return void 0;
+    return { identity: void 0, refused: false };
   } finally {
     clearTimeout(timer);
   }
 }
+async function describeAccount(serviceUrl, credential, fetchImpl = fetch) {
+  return (await askAccount(serviceUrl, credential, fetchImpl)).identity;
+}
 function accountLabel(identity, storedAccountId, verbose2 = false) {
   const accountId = identity?.accountId ?? storedAccountId;
   if (identity?.email !== void 0 && identity.email.trim() !== "") {
@@ -3412,7 +3666,7 @@ function renderBuildRecordMarkdown(record2) {
     "",
     `**Format:** \`${record2.format}\` (markdown + JSON pair; portable, readable without Halfcycle systems)`,
     "",
-    "> This Build Record was assembled automatically at phase close by the method bundle (`packages/bundle`). Every data field below is projected from the companion JSON \u2014 no record content is hand-authored.",
+    "> This Build Record was assembled automatically at phase close by `npx halfcycle close-phase`. Every data field below is projected from the companion JSON \u2014 no record content is hand-authored.",
     "",
     `**Engagement:** ${record2.engagement} (${record2.engagementType})`,
     `**Phase:** ${phase.id} \u2014 ${phase.name}`,
@@ -3432,7 +3686,7 @@ function renderBuildRecordMarkdown(record2) {
     `- **Tools:** ${record2.delivered.tools.join(", ")}`,
     `- **Dogfood:** ${record2.delivered.dogfood}`,
     "",
-    guardsList ? `Guards evaluated (INV-007-safe results): ${guardsList}. *(Guard \`channel\`/\`version\` are guard-asset metadata, excluded from the v1 record \u2014 INV-007/INV-001.)*` : "No guards fired during this phase.",
+    guardsList ? `Guards evaluated (results only): ${guardsList}. *(What a guard reported about this phase is recorded; the guard's own definition and its history are not.)*` : "No guards fired during this phase.",
     "",
     `## Acceptance (independent walk \u2014 walker ${record2.acceptance.walker})`,
     "",
@@ -3444,7 +3698,7 @@ function renderBuildRecordMarkdown(record2) {
     ""
   ];
   if (record2.acceptance.inv002ProdBypassProbe) {
-    lines.push(`**INV-002 production bypass probe:** ${record2.acceptance.inv002ProdBypassProbe.result} \u2014 ${record2.acceptance.inv002ProdBypassProbe.detail}`, "");
+    lines.push(`**Production bypass probe:** ${record2.acceptance.inv002ProdBypassProbe.result} \u2014 ${record2.acceptance.inv002ProdBypassProbe.detail}`, "");
   }
   lines.push("## Gates that earned their keep", "", `**${record2.gatesEarnedKeep.defectsCaughtPreHuman}** defects were caught by the gates before the human walk; the walk itself found **${record2.gatesEarnedKeep.bugsReachingHumanWalk}**. Named: ${record2.gatesEarnedKeep.named.join("; ")}.`, "", "## Instruments", "", `- **Marginal-cost self-accounting:** ${record2.instruments.marginalCostSelfAccounting}`, `- **COE add-rate:** seam-new ${record2.instruments.coeAddRate.seamNew}, seam-repeat ${record2.instruments.coeAddRate.seamRepeat}, model-limitation ${record2.instruments.coeAddRate.modelLimitation}. ${record2.instruments.coeAddRate.notes}`, "", "## Invariants exercised", "", record2.invariantsExercised.join(", "), "", "## Deviations & decisions recorded", "", ...record2.deviations.map((d) => `- ${d}`), "", "## Tasks", "", `- **Planned:** ${record2.tasks.planned} \xB7 **Landed:** ${record2.tasks.landed} \xB7 **Cancelled:** ${record2.tasks.cancelled.length > 0 ? record2.tasks.cancelled.join(", ") : "none"}`, "");
   return lines.join("\n");
@@ -3837,15 +4091,115 @@ async function closePhase(credential, phase, outcome, close, home, repoRoot) {
   return { engagementId: body.engagementId, status: body.status, stampFailure, closeRecord };
 }
 
+// dist/ci-bind.js
+function parseCiRepositoryArg(arg) {
+  const parts = arg.split("/");
+  if (parts.length !== 2)
+    return null;
+  const [owner, repo] = parts;
+  if (owner === void 0 || owner.trim() === "")
+    return null;
+  if (repo === void 0 || repo.trim() === "")
+    return null;
+  return { owner, repo };
+}
+var CiBindRefused = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "CiBindRefused";
+  }
+  /** Is this the ONE arm signing in again can fix — see this file's header. */
+  get authRefused() {
+    return this.status === 401;
+  }
+  /**
+   * Is this "ours to fix, try again", not "yours to fix"? The question is not
+   * mechanical (did a handler run) — it is what a developer reading the message
+   * does next. `502`/`504` are the reverse proxy in front of the published origin
+   * answering for a control plane that is down or slow, with an HTML body this
+   * file's own `requestBinding` cannot parse, so the message would otherwise
+   * degrade to a bare "the URL returned 502". `503` is `resolveAccount`'s own
+   * fail-closed refusal when it could not reach the token store — the caller's
+   * credential was never actually checked, and its posture is emphatic this is NOT
+   * a "no". **`500` belongs beside them, not with the 4xx arms.** It is an
+   * unhandled throw: nothing decided the request's merits, and the bind may even
+   * have half-happened if the throw landed after a commit. On this route the
+   * body is the same degraded "the URL returned 500" a 502/504 produces — an
+   * internal path echoed back with no advice — so `refused (500)` would send a
+   * developer to re-check ownership, the repository name and whether it is bound
+   * elsewhere: every 4xx question, none of them this status's actual cause.
+   *
+   * So this is every `5xx`, not an enumerated set of three — the boundary is
+   * "did any handler decide yes or no", and a 4xx is the only family that ever did.
+   */
+  get unavailable() {
+    return this.status >= 500 && this.status < 600;
+  }
+};
+async function requestBinding(method, serviceUrl, engagementId, repository, credential, noun) {
+  const url = `${serviceUrl.replace(/\/+$/, "")}/engagements/${encodeURIComponent(engagementId)}/ci-bindings/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}`;
+  let res;
+  try {
+    res = await fetch(url, { method, headers: { authorization: `Bearer ${credential}` } });
+  } catch (err) {
+    throw new Error(`[halfcycle] Could not reach the Halfcycle service at ${url}: ${err instanceof Error ? err.message : String(err)}. Nothing was ${noun}.`);
+  }
+  if (res.status === 204)
+    return;
+  const body = await res.json().catch(() => null);
+  const message = typeof body?.message === "string" ? body.message : `${url} returned ${res.status}.`;
+  throw new CiBindRefused(res.status, message);
+}
+async function setCiBinding(action, serviceUrl, engagementId, repository, deps = {}) {
+  const noun = action === "bind" ? "bound" : "unbound";
+  const signInDeps = {
+    ...deps,
+    reason: deps.reason ?? (action === "bind" ? "trust this repository for this engagement's CI" : "stop trusting this repository for this engagement's CI")
+  };
+  let credential = await obtainCredential(serviceUrl, signInDeps);
+  for (; ; ) {
+    try {
+      await requestBinding(action === "bind" ? "PUT" : "DELETE", serviceUrl, engagementId, repository, credential.credential, noun);
+      return;
+    } catch (err) {
+      if (!(err instanceof CiBindRefused) || !err.authRefused)
+        throw err;
+      const replacement = await replaceRefusedCredential(serviceUrl, credential, signInDeps);
+      if (replacement === null) {
+        throw new SignInRefused(`ci-${action}-${err.status}`, `${err.message} ${refusedCredentialRemedy(credential.source)} Nothing was ${noun}.`);
+      }
+      process.stdout.write(`[halfcycle] Your saved Halfcycle sign-in was refused \u2014 signing you in again.
+`);
+      credential = replacement;
+    }
+  }
+}
+function bindCiRepository(serviceUrl, engagementId, repository, deps = {}) {
+  return setCiBinding("bind", serviceUrl, engagementId, repository, deps);
+}
+function unbindCiRepository(serviceUrl, engagementId, repository, deps = {}) {
+  return setCiBinding("unbind", serviceUrl, engagementId, repository, deps);
+}
+
 // dist/cli-contract.js
-var CLI_VERBS = ["install", "check-drift", "build-record", "open-phase", "close-phase"];
+var CLI_VERBS = ["install", "check-drift", "build-record", "open-phase", "close-phase", "ci"];
 var CONTRACTS = [
-  // `install`, `check-drift` and `build-record` take positionals and no required
-  // flags. They are declared so the verb set has ONE home — a remedy naming a verb
-  // this CLI does not have is the same defect as one missing a flag.
+  // `install`, `check-drift`, `build-record` and `ci` take positionals and no
+  // required flags. They are declared so the verb set has ONE home — a remedy
+  // naming a verb this CLI does not have is the same defect as one missing a flag.
+  //
+  // `ci`'s two forms (`ci bind <owner>/<repo>`, `ci unbind <owner>/<repo>`) take a
+  // sub-action and a repository as POSITIONALS, not flags — this table answers only
+  // *which flags must an invocation carry*, and neither form has one (T-11,
+  // `ci-oidc-token-exchange`). The route it calls declares no wire shape either
+  // (path segments in, `204` out — T-05), so there is no schema for an argument
+  // here to disagree with.
   { verb: "install", required: [], conditional: [] },
   { verb: "check-drift", required: [], conditional: [] },
   { verb: "build-record", required: [], conditional: [] },
+  { verb: "ci", required: [], conditional: [] },
   {
     verb: "open-phase",
     required: [
@@ -3879,7 +4233,7 @@ var CONTRACTS = [
       {
         flag: "--verdict",
         takesValue: true,
-        missingMessage: `halfcycle close-phase: --verdict must be "clean" or "defects" \u2014 it is the acceptance walk's own verdict (INV-009) and nothing derives it for you.`
+        missingMessage: `halfcycle close-phase: --verdict must be "clean" or "defects" \u2014 it is the acceptance walk's own verdict and nothing derives it for you.`
       },
       {
         flag: "--actor",
@@ -4038,10 +4392,9 @@ function openingBannerContent(projectDir, env = process.env, probes = REAL_PROBE
     fact("Claude Code", probes.claudeCodeVersion()),
     fact("Project", project, name),
     fact("Status", status, installed === void 0 ? "new" : "installed"),
-    // `Website`, NOT `Plane` (W-3, #868). "Plane" is our internal word for the control
-    // plane; the developer reading this has never heard it, and raw method vocabulary
-    // reaching a client surface is a recorded finding class in this product. The row
-    // answers *which Halfcycle is this*, and an address is the answer they recognise.
+    // `Website`, NOT `Plane` — see this function's docblock. (No issue number here:
+    // a comment beside a property survives into the published entry, unlike a
+    // leading docblock, which esbuild drops.)
     fact("Website", probes.websiteHost(env))
   ].filter((f) => f !== void 0);
   return {
@@ -4121,6 +4474,8 @@ var USAGE = `  halfcycle [install] [target-repo] [engagement-id] [self-build|cli
   halfcycle build-record <phase> [--repo <root>]
   halfcycle open-phase <phase|--none> --actor "\u2026" (--evidence "\u2026" | --override --reason "\u2026") [--repo <root>]
   halfcycle close-phase <phase> --verdict <clean|defects> --actor "\u2026" [--finding "\u2026"]\u2026 [--override --reason "\u2026"] [--repo <root>]
+  halfcycle ci bind <owner>/<repo> [--repo <root>]
+  halfcycle ci unbind <owner>/<repo> [--repo <root>]
 
   --quiet / -q: print no opening banner (any command)
   --verbose / -v: print full run detail (paths written, merged, skipped) on install
@@ -4135,7 +4490,7 @@ function isHalfcycleMonorepo(dir) {
 }
 async function main() {
   const [cmd, ...rest] = args;
-  const bareTarget = cmd !== void 0 && !cmd.startsWith("-") && !/^(check-drift|build-record|open-phase|close-phase)$/.test(cmd);
+  const bareTarget = cmd !== void 0 && !cmd.startsWith("-") && !/^(check-drift|build-record|open-phase|close-phase|ci)$/.test(cmd);
   const installArm = cmd === "install" || cmd === void 0 || bareTarget;
   const positionals = cmd === "install" ? rest : args;
   const targetRepo = installArm ? positionals[0] ?? process.cwd() : process.cwd();
@@ -4176,7 +4531,9 @@ ${USAGE}`);
       }
       const pinned = readPinnedEngagement(targetRepo);
       const requestedId = engagementIdArg ?? pinned?.engagementId;
-      const reusable = pinned !== null && pinned.engagementId === requestedId ? pinned.credential : void 0;
+      const held = pinned !== null && pinned.engagementId === requestedId ? pinned.credential : void 0;
+      const heldAnswer = held !== void 0 ? await askAccount(held.serviceUrl, held.token) : void 0;
+      const reusable = heldAnswer?.refused === true ? void 0 : held;
       let engagementId;
       let credential;
       let notThisAccountMessage;
@@ -4322,7 +4679,7 @@ ${USAGE}`);
 `);
       }
       reportClaudeCodeVersion(verbose);
-      const identity = actingIdentity ?? (credential ? await describeAccount(credential.serviceUrl, credential.token) : void 0);
+      const identity = actingIdentity ?? heldAnswer?.identity ?? (credential && heldAnswer === void 0 ? await describeAccount(credential.serviceUrl, credential.token) : void 0);
       const written = result.writtenPaths.length;
       const merged = result.mergedPaths.length;
       process.stdout.write(`[halfcycle] Signed in as ${accountLabel(identity, actingAccountId, verbose)}
@@ -4335,6 +4692,8 @@ ${USAGE}`);
         process.stdout.write(`[halfcycle] Next: open this folder in Claude Code \u2014 accept the workspace-trust prompt, it is expected \u2014 then run /halfcycle-setup and answer what it asks about your project
 `);
         process.stdout.write(`[halfcycle] Claude Code will also ask permission the first time Halfcycle needs to look up your next step. Choose allow \u2014 without it nothing can run.
+`);
+        process.stdout.write(`[halfcycle] To check changes in CI too: run \`npx halfcycle ci bind <owner>/<repo>\` in this folder once, then paste the job from .halfcycle/ci-stanza.yml into a workflow \u2014 there is no secret to store.
 `);
       }
       if (credential) {
@@ -4593,6 +4952,69 @@ halfcycle close-phase: until ${closed.stampFailure.path} can be written, guard e
         return;
       }
       process.stderr.write(`halfcycle close-phase failed: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+    return;
+  }
+  if (cmd === "ci") {
+    const repoRoot = flagValue(rest, "--repo") ?? process.cwd();
+    const positionals2 = rest.filter((token, i) => !token.startsWith("--") && !(i > 0 && rest[i - 1] === "--repo"));
+    const action = positionals2[0];
+    const repositoryArg = positionals2[1];
+    if (action !== "bind" && action !== "unbind") {
+      process.stderr.write("halfcycle ci: name bind or unbind.\n  halfcycle ci bind <owner>/<repo> [--repo <root>]\n  halfcycle ci unbind <owner>/<repo> [--repo <root>]\n");
+      process.exit(2);
+      return;
+    }
+    if (repositoryArg === void 0) {
+      process.stderr.write(`halfcycle ci ${action}: name the repository, as owner/repo.
+`);
+      process.exit(2);
+      return;
+    }
+    const repository = parseCiRepositoryArg(repositoryArg);
+    if (repository === null) {
+      process.stderr.write(`halfcycle ci ${action}: "${repositoryArg}" is not a repository \u2014 give it as owner/repo, exactly as GitHub spells it, for example acme/widgets.
+`);
+      process.exit(2);
+      return;
+    }
+    const pin = readBundlePin(repoRoot);
+    if (pin === null || pin.engagementId === "") {
+      process.stderr.write(`halfcycle ci ${action}: ${join11(repoRoot, ".halfcycle", "bundle.json")} names no Halfcycle engagement. Run \`npx halfcycle\` here first.
+`);
+      process.exit(1);
+      return;
+    }
+    try {
+      const controlOrigin = resolveControlOrigin(process.env);
+      const label = `${repository.owner}/${repository.repo}`;
+      if (action === "bind") {
+        await bindCiRepository(controlOrigin.origin, pin.engagementId, repository);
+        process.stdout.write(`[halfcycle] ${label} now trusts this engagement's CI \u2014 a workflow there granting both \`contents: read\` and \`id-token: write\` can authenticate with no stored secret. Both lines: declaring any permission replaces the defaults, so naming only the identity token stops a private repository checking out.
+`);
+      } else {
+        await unbindCiRepository(controlOrigin.origin, pin.engagementId, repository);
+        process.stdout.write(`[halfcycle] ${label} no longer trusts this engagement's CI.
+`);
+      }
+      process.exit(0);
+    } catch (err) {
+      if (err instanceof SignInRefused) {
+        process.stderr.write(`halfcycle ci ${action}: ${err.message}
+`);
+        process.exit(1);
+        return;
+      }
+      if (err instanceof CiBindRefused) {
+        const label = err.unavailable ? `temporarily unavailable (${err.status})` : `refused (${err.status})`;
+        process.stderr.write(`halfcycle ci ${action}: ${label}. ${err.message}
+`);
+        process.exit(1);
+        return;
+      }
+      process.stderr.write(`halfcycle ci ${action} failed: ${err instanceof Error ? err.message : String(err)}
 `);
       process.exit(1);
     }