halfcycle 0.3.23 → 0.3.25

package/bin/bin.bundle.mjs

@@ -14,75 +14,6 @@ function resolveGuardOrigin(env) {
   return { origin: DEFAULT_GUARD_ORIGIN, source: "default" };
 }
 
-// dist/config.js
-var EXCERPT_DEFAULTS = {
-  maxCharsPerExcerpt: 200,
-  maxExcerptsPerFile: 5,
-  maxExcerptsPerChangeSet: 20
-};
-function readConfig() {
-  const guardServiceUrl = resolveGuardOrigin(process.env).origin;
-  const guardServiceToken = process.env["GUARD_SERVICE_TOKEN"];
-  const guardEngagementId = process.env["GUARD_ENGAGEMENT_ID"];
-  const missing = [];
-  if (!guardServiceToken)
-    missing.push("GUARD_SERVICE_TOKEN");
-  if (!guardEngagementId)
-    missing.push("GUARD_ENGAGEMENT_ID");
-  if (missing.length > 0)
-    return { config: null, missing };
-  return {
-    config: {
-      guardServiceUrl,
-      guardServiceToken,
-      guardEngagementId
-    }
-  };
-}
-function readNeverConfiguredReason() {
-  return process.env["HALFCYCLE_NOT_THIS_ACCOUNT"] === "1" ? "not-this-account" : "no-credential-yet";
-}
-function readExcerptConfig() {
-  const raw = process.env["HALFCYCLE_SOURCE_EXCERPTS"];
-  const enabled = (raw ?? "").trim().toLowerCase() === "true";
-  const readCap = (name, fallback) => {
-    const v = process.env[name];
-    if (v === void 0)
-      return fallback;
-    const n = Number.parseInt(v, 10);
-    return Number.isFinite(n) && n > 0 ? n : fallback;
-  };
-  return {
-    enabled,
-    maxCharsPerExcerpt: readCap("HALFCYCLE_EXCERPT_MAX_CHARS", EXCERPT_DEFAULTS.maxCharsPerExcerpt),
-    maxExcerptsPerFile: readCap("HALFCYCLE_EXCERPT_MAX_PER_FILE", EXCERPT_DEFAULTS.maxExcerptsPerFile),
-    maxExcerptsPerChangeSet: readCap("HALFCYCLE_EXCERPT_MAX_PER_CHANGESET", EXCERPT_DEFAULTS.maxExcerptsPerChangeSet)
-  };
-}
-function readDiffBaseConfig() {
-  const raw = process.env["HALFCYCLE_DIFF_BASE"];
-  const trimmed = (raw ?? "").trim();
-  if (!trimmed)
-    return void 0;
-  if (/^0+$/.test(trimmed))
-    return void 0;
-  return trimmed;
-}
-function readTelemetryConfig() {
-  return {
-    controlTelemetryUrl: process.env["CONTROL_TELEMETRY_URL"],
-    // Reuse GUARD_SERVICE_TOKEN as the per-engagement bearer token for telemetry.
-    // The control plane validates the same token on POST /telemetry (Phase 1).
-    controlTelemetryToken: process.env["GUARD_SERVICE_TOKEN"],
-    // Per-engagement log dir injected by the guard-runner.sh wrapper (E1-T-02).
-    // Absent → emit.ts defaults to ~/.halfcycle/guard-eval-log/.
-    guardEvalLogDir: process.env["HALFCYCLE_GUARD_EVAL_LOG_DIR"],
-    // Phase source injected by the guard-runner.sh wrapper (E1-T-03, #61 seam).
-    // Absent → the run is unphased.
-    phase: process.env["HALFCYCLE_PHASE"]
-  };
-}
-
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -14597,6 +14528,220 @@ function date4(params) {
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
 
+// ../core/dist/guard-record.js
+var severitySchema = external_exports.enum(["info", "warn", "block"]);
+var channelSchema = external_exports.enum(["stable", "candidate", "rented"]);
+var matcherKindSchema = external_exports.enum(["grep", "ast", "integrationTest", "llm"]);
+var matcherConfigSchema = external_exports.record(external_exports.string(), external_exports.unknown());
+var grepMatcherSchema = external_exports.object({ kind: external_exports.literal("grep"), config: matcherConfigSchema }).strict();
+var astMatcherSchema = external_exports.object({ kind: external_exports.literal("ast"), config: matcherConfigSchema }).strict();
+var integrationTestMatcherSchema = external_exports.object({ kind: external_exports.literal("integrationTest"), config: matcherConfigSchema }).strict();
+var llmMatcherSchema = external_exports.object({ kind: external_exports.literal("llm"), config: matcherConfigSchema }).strict();
+var matcherSchema = external_exports.discriminatedUnion("kind", [
+  grepMatcherSchema,
+  astMatcherSchema,
+  integrationTestMatcherSchema,
+  llmMatcherSchema
+]);
+
+// ../core/dist/credential-format.js
+var HALFCYCLE_DIR_NAME = ".halfcycle";
+var ENGAGEMENTS_DIR_NAME = "engagements";
+var ENGAGEMENT_ENV_FILENAME = "env";
+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: {} };
+  }
+}
+
+// ../core/dist/ci-audience.js
+var HALFCYCLE_OIDC_AUDIENCE = "https://halfcycle.ai";
+
+// dist/control-origin.js
+var DEFAULT_CONTROL_ORIGIN = "https://control.halfcycle.ai";
+function resolveControlOrigin(env) {
+  const configured = env["HALFCYCLE_SERVICE_URL"]?.trim();
+  if (configured)
+    return { origin: normaliseOrigin(configured), source: "environment" };
+  return { origin: DEFAULT_CONTROL_ORIGIN, source: "default" };
+}
+
+// dist/config.js
+var EXCERPT_DEFAULTS = {
+  maxCharsPerExcerpt: 200,
+  maxExcerptsPerFile: 5,
+  maxExcerptsPerChangeSet: 20
+};
+function readConfig() {
+  const guardServiceUrl = readGuardOrigin().origin;
+  const guardServiceToken = process.env["GUARD_SERVICE_TOKEN"];
+  const guardEngagementId = process.env["GUARD_ENGAGEMENT_ID"];
+  const missing = [];
+  if (!guardServiceToken)
+    missing.push("GUARD_SERVICE_TOKEN");
+  if (!guardEngagementId)
+    missing.push("GUARD_ENGAGEMENT_ID");
+  if (missing.length > 0)
+    return { config: null, missing };
+  return {
+    config: {
+      guardServiceUrl,
+      guardServiceToken,
+      guardEngagementId
+    }
+  };
+}
+function readNeverConfiguredReason() {
+  return process.env["HALFCYCLE_NOT_THIS_ACCOUNT"] === "1" ? "not-this-account" : "no-credential-yet";
+}
+function readGuardOrigin() {
+  return resolveGuardOrigin(process.env);
+}
+function readActionsOidcEnv() {
+  const requestUrl = process.env["ACTIONS_ID_TOKEN_REQUEST_URL"]?.trim();
+  const requestToken = process.env["ACTIONS_ID_TOKEN_REQUEST_TOKEN"]?.trim();
+  if (!requestUrl || !requestToken)
+    return void 0;
+  return { requestUrl, requestToken };
+}
+function readControlOrigin() {
+  return resolveControlOrigin(process.env);
+}
+function readEnvFilePath() {
+  const raw = process.env["HALFCYCLE_ENV_FILE"]?.trim();
+  return raw ? raw : void 0;
+}
+function readExcerptConfig() {
+  const raw = process.env["HALFCYCLE_SOURCE_EXCERPTS"];
+  const enabled = (raw ?? "").trim().toLowerCase() === "true";
+  const readCap = (name, fallback) => {
+    const v = process.env[name];
+    if (v === void 0)
+      return fallback;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+  };
+  return {
+    enabled,
+    maxCharsPerExcerpt: readCap("HALFCYCLE_EXCERPT_MAX_CHARS", EXCERPT_DEFAULTS.maxCharsPerExcerpt),
+    maxExcerptsPerFile: readCap("HALFCYCLE_EXCERPT_MAX_PER_FILE", EXCERPT_DEFAULTS.maxExcerptsPerFile),
+    maxExcerptsPerChangeSet: readCap("HALFCYCLE_EXCERPT_MAX_PER_CHANGESET", EXCERPT_DEFAULTS.maxExcerptsPerChangeSet)
+  };
+}
+function readDiffBaseConfig() {
+  const raw = process.env["HALFCYCLE_DIFF_BASE"];
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed)
+    return void 0;
+  if (/^0+$/.test(trimmed))
+    return void 0;
+  return trimmed;
+}
+function readTelemetryConfig() {
+  return {
+    controlTelemetryUrl: process.env["CONTROL_TELEMETRY_URL"],
+    // Reuse GUARD_SERVICE_TOKEN as the per-engagement bearer token for telemetry.
+    // The control plane validates the same token on POST /telemetry (Phase 1).
+    controlTelemetryToken: process.env["GUARD_SERVICE_TOKEN"],
+    // Per-engagement log dir injected by the guard-runner.sh wrapper (E1-T-02).
+    // Absent → emit.ts defaults to ~/.halfcycle/guard-eval-log/.
+    guardEvalLogDir: process.env["HALFCYCLE_GUARD_EVAL_LOG_DIR"],
+    // Phase source injected by the guard-runner.sh wrapper (E1-T-03, #61 seam).
+    // Absent → the run is unphased.
+    phase: process.env["HALFCYCLE_PHASE"]
+  };
+}
+
 // ../events/dist/evaluation.js
 var envRefSchema = external_exports.object({
   name: external_exports.string(),
@@ -14671,22 +14816,6 @@ var evaluationRequestSchema = external_exports.object({
   clientCapabilities: external_exports.array(external_exports.string()).optional()
 }).strict();
 
-// ../core/dist/guard-record.js
-var severitySchema = external_exports.enum(["info", "warn", "block"]);
-var channelSchema = external_exports.enum(["stable", "candidate", "rented"]);
-var matcherKindSchema = external_exports.enum(["grep", "ast", "integrationTest", "llm"]);
-var matcherConfigSchema = external_exports.record(external_exports.string(), external_exports.unknown());
-var grepMatcherSchema = external_exports.object({ kind: external_exports.literal("grep"), config: matcherConfigSchema }).strict();
-var astMatcherSchema = external_exports.object({ kind: external_exports.literal("ast"), config: matcherConfigSchema }).strict();
-var integrationTestMatcherSchema = external_exports.object({ kind: external_exports.literal("integrationTest"), config: matcherConfigSchema }).strict();
-var llmMatcherSchema = external_exports.object({ kind: external_exports.literal("llm"), config: matcherConfigSchema }).strict();
-var matcherSchema = external_exports.discriminatedUnion("kind", [
-  grepMatcherSchema,
-  astMatcherSchema,
-  integrationTestMatcherSchema,
-  llmMatcherSchema
-]);
-
 // ../events/dist/result.js
 var firedGuardSchema = external_exports.object({
   guardId: external_exports.string(),
@@ -14745,6 +14874,173 @@ var wireErrorSchema = external_exports.object({
   message: external_exports.string()
 }).strict();
 
+// ../events/dist/state.js
+var utcIso8601 = external_exports.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 = external_exports.string().regex(/^(l[0-5](-l[0-5])?|xl)\.[a-z0-9-]+$/);
+var methodVersionSchema = external_exports.string().regex(/^\d+\.\d+\.\d+$/);
+var anchorPathRegex = /^(?!\/)(?!.*#)(?!method\/)(?!(.*\/)?docs\/method\/).+$/;
+var recordKindSchema = external_exports.enum(["artefact", "step-run", "gate", "intervention"]);
+var methodLayerSchema = external_exports.enum(["l0", "l1", "l2", "l3", "l3-l4", "l4", "l5", "xl"]);
+var evidenceKindSchema = external_exports.enum(["anchor", "diff", "repro", "question-answer", "no-op"]);
+var declarableEvidenceKindSchema = external_exports.enum(["anchor", "diff", "repro", "question-answer"]);
+var dispositionSchema = external_exports.enum([
+  "prevented",
+  "corrected-in-spec",
+  "corrected-in-scope",
+  "blocked-in-code",
+  "flagged",
+  "auto-fixed",
+  "surfaced",
+  "filed-forward"
+]);
+var mechanismSchema = external_exports.enum(["guard", "verdict", "served-step", "method-step"]);
+var artefactStateSchema = external_exports.enum(["created", "updated"]);
+var QUALIFIED_OUTCOMES = ["declined", "parked"];
+var qualifiedOutcomeSchema = external_exports.enum(QUALIFIED_OUTCOMES);
+function isQualifiedOutcome(outcome) {
+  return QUALIFIED_OUTCOMES.includes(outcome);
+}
+var runOutcomeSchema = external_exports.enum([
+  "completed",
+  "attempted-failed",
+  ...QUALIFIED_OUTCOMES
+]);
+var gateKindSchema = external_exports.enum(["approval", "mechanical"]);
+var gateVerdictSchema = external_exports.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 = external_exports.object({
+  kind: external_exports.literal("anchor"),
+  path: external_exports.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: external_exports.number().optional()
+}).strict();
+var diffEvidenceSchema = external_exports.object({
+  kind: external_exports.literal("diff"),
+  ref: external_exports.string()
+}).strict();
+var reproEvidenceSchema = external_exports.object({
+  kind: external_exports.literal("repro"),
+  steps: external_exports.string().max(2e3)
+}).strict();
+var questionAnswerEvidenceSchema = external_exports.object({
+  kind: external_exports.literal("question-answer"),
+  question: external_exports.string().max(2e3),
+  before: external_exports.string().max(2e3),
+  after: external_exports.string().max(2e3)
+}).strict();
+var noOpEvidenceSchema = external_exports.object({
+  kind: external_exports.literal("no-op"),
+  inspected: external_exports.string().max(2e3),
+  unchangedBecause: external_exports.string().max(2e3)
+}).strict();
+var evidenceSchema = external_exports.discriminatedUnion("kind", [
+  anchorEvidenceSchema,
+  diffEvidenceSchema,
+  reproEvidenceSchema,
+  questionAnswerEvidenceSchema,
+  noOpEvidenceSchema
+]);
+var stateRecordEnvelopeSchema = external_exports.object({
+  format: external_exports.literal(STATE_RECORD_FORMAT),
+  recordKind: recordKindSchema,
+  recordId: external_exports.string().uuid(),
+  methodVersion: methodVersionSchema,
+  engagementId: external_exports.string(),
+  stepId: stepIdSchema,
+  // Immutable: names when the thing happened, never when a later disposition
+  // moved.
+  occurredAt: utcIso8601,
+  // 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: utcIso8601,
+  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: external_exports.string().optional()
+});
+var artefactRefSchema = external_exports.object({
+  name: external_exports.string(),
+  parent: external_exports.string()
+}).strict();
+var artefactRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: external_exports.literal("artefact"),
+  artefactRef: artefactRefSchema,
+  // Some layer wrote it, by construction — an empty array is not a legitimate
+  // state, so the schema says so.
+  writtenByLayers: external_exports.array(methodLayerSchema).min(1),
+  state: artefactStateSchema
+}).strict();
+var stepRunRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: external_exports.literal("step-run"),
+  runOutcome: runOutcomeSchema,
+  failureReason: external_exports.string().optional(),
+  outcomeReason: external_exports.string().max(2e3).optional()
+}).strict().superRefine((rec, ctx) => {
+  if (rec.runOutcome === "attempted-failed" && rec.failureReason === void 0) {
+    ctx.addIssue({
+      code: external_exports.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: external_exports.ZodIssueCode.custom,
+      path: ["failureReason"],
+      message: "failureReason is only present when runOutcome is 'attempted-failed'"
+    });
+  }
+  const issue2 = outcomeReasonIssue(rec.runOutcome, rec.outcomeReason);
+  if (issue2) {
+    ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["outcomeReason"], ...issue2 });
+  }
+});
+var gateRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: external_exports.literal("gate"),
+  gateKind: gateKindSchema,
+  verdict: gateVerdictSchema,
+  actor: external_exports.string(),
+  outcomeReason: external_exports.string().max(2e3).optional()
+}).strict().superRefine((rec, ctx) => {
+  const issue2 = outcomeReasonIssue(rec.verdict, rec.outcomeReason);
+  if (issue2) {
+    ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["outcomeReason"], ...issue2 });
+  }
+});
+var interventionRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: external_exports.literal("intervention"),
+  layer: methodLayerSchema,
+  mechanism: mechanismSchema,
+  severity: severitySchema,
+  disposition: dispositionSchema,
+  summary: external_exports.string().max(2e3)
+}).strict();
+var stateRecordSchema = external_exports.discriminatedUnion("recordKind", [
+  artefactRecordSchema,
+  stepRunRecordSchema,
+  gateRecordSchema,
+  interventionRecordSchema
+]);
+
 // ../events/dist/phase-identity.js
 var PHASE_SEGMENT_PREFIX = "phase-";
 function isValidPhaseIdentity(identity) {
@@ -14801,25 +15097,281 @@ function describeIdentity(identity) {
   return `(a ${typeof identity})`;
 }
 
-// dist/client.js
-var REQUEST_TIMEOUT_MS = 1e4;
-async function evaluate(url2, token, request, fetchFn = globalThis.fetch) {
-  return attempt(
-    url2,
-    token,
-    request,
-    fetchFn,
-    /* retry */
-    true
-  );
-}
-async function attempt(url2, token, request, fetchFn, retry) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-  let response;
-  try {
-    response = await fetchFn(`${url2}/evaluate`, {
-      method: "POST",
+// ../events/dist/credential-wire.js
+var engagementCredentialResponseSchema = external_exports.object({
+  engagementId: external_exports.string(),
+  sessionToken: external_exports.string(),
+  mcpUrl: external_exports.string(),
+  guardUrl: external_exports.string(),
+  controlTelemetryUrl: external_exports.string()
+}).strict();
+var ciTokenExchangeResponseSchema = external_exports.object({
+  token: external_exports.string(),
+  expiresAt: utcIso8601,
+  engagementId: external_exports.string()
+}).strict();
+
+// dist/hook-protocol.js
+import { writeSync } from "node:fs";
+function emitBlock(reason) {
+  process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
+  process.exit(0);
+}
+function emitWarning(text) {
+  process.stdout.write(text + "\n");
+}
+function emitInfraWarning(message) {
+  process.stdout.write(`[Halfcycle] WARNING: Guard service unavailable \u2014 ${message}. Session continues (fail-open).
+`);
+}
+function emitLocalFault(message) {
+  process.stdout.write(`[Halfcycle] WARNING: Local fault \u2014 ${message}. The guard service was not contacted. Session continues (fail-open).
+`);
+}
+function emitContractFault(message) {
+  process.stdout.write(`[Halfcycle] WARNING: Guard response could not be understood \u2014 ${message}
+This is not a service outage: the guard service answered. The suspect is this repository's own installed halfcycle runner, which is out of date with what the service now sends. Update it: run "npx halfcycle" in this repository, then retry. Session continues (fail-open).
+`);
+}
+var UNCONFIGURED_EXIT_TOOL_USE = 2;
+var UNCONFIGURED_EXIT_STOP_FAMILY = 1;
+function emitNeverConfigured(missing, exitCode, reason) {
+  writeSync(2, neverConfiguredReport(missing, reason));
+  process.exitCode = exitCode;
+}
+var HOOK_REMEDY = `Fix it by running "npx halfcycle" in this repository: it may open your browser to sign in first, then writes this engagement's credentials to ~/.halfcycle \u2014 outside the repository \u2014 and the hook loads them itself.`;
+var PERMISSIONS_BLOCK = "\n    permissions:\n      contents: read\n      id-token: write\n\n";
+var BOTH_LINES_SENTENCE = "BOTH LINES. Declaring any permission replaces the defaults rather than adding to them, so a block naming only the identity token takes read access away from the checkout step and a private repository stops checking out before this check is reached.";
+var CI_REMEDY = "This job cannot vouch for anything, because it has no way to prove which project it belongs to. Add this to the workflow \u2014 at the top of the file, or on this job:\n" + PERMISSIONS_BLOCK + `${BOTH_LINES_SENTENCE} Then, once, on your own machine in this project, if you have not already: \`npx halfcycle ci bind <owner>/<repo>\`. That is the whole configuration \u2014 there is no secret to store. The older setup, GUARD_SERVICE_TOKEN and GUARD_ENGAGEMENT_ID supplied as repository secrets, still works unchanged, and a job that has both needs neither line.`;
+function neverConfiguredMessage(missing, remedy, label = "[Halfcycle]") {
+  return `${label} GUARD NEVER CONFIGURED \u2014 this repository has no guard coverage.
+No evaluation was attempted, because there is nothing to attempt one with: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} absent.
+This is not a service outage. It means the guard has never run here \u2014 not on this change, and not on any change before it.
+${remedy}
+`;
+}
+function notThisAccountReport(label) {
+  return `${label} This project belongs to another Halfcycle account. Halfcycle is Solo today \u2014 one person works on a project at a time \u2014 so no credential exists for this machine and none will be issued. Nothing here needs fixing; this copy simply is not checked. Ask the project's owner for view access, or \u2014 if this account is wrong \u2014 sign in as the one that owns the project and run "npx halfcycle" again.
+`;
+}
+function neverConfiguredReport(missing, reason, label = "[Halfcycle]") {
+  switch (reason) {
+    case "no-credential-yet":
+      return neverConfiguredMessage(missing, HOOK_REMEDY, label);
+    case "not-this-account":
+      return notThisAccountReport(label);
+  }
+}
+var CREDENTIAL_REJECTED_STATUSES = /* @__PURE__ */ new Set([401, 403]);
+function classifyFailure(failure) {
+  if (failure.kind === "contract-error") {
+    return {
+      kind: "contract",
+      message: failure.message,
+      label: "contract error",
+      reason: `contract error: ${failure.message}`
+    };
+  }
+  if (failure.kind === "wire-error" && CREDENTIAL_REJECTED_STATUSES.has(failure.statusCode)) {
+    const label = `credential rejected (${failure.statusCode})`;
+    return {
+      kind: "credential",
+      statusCode: failure.statusCode,
+      message: failure.message,
+      label,
+      reason: `${label}: ${failure.message}`
+    };
+  }
+  return {
+    kind: "service",
+    message: failure.message,
+    // Unchanged wording for this class ON PURPOSE — a genuine outage still says
+    // exactly what it said before, and still fails open locally. This task moved
+    // ONE condition out of this branch; it did not redefine the branch.
+    label: "infrastructure failure",
+    reason: `infrastructure failure: ${failure.message}`
+  };
+}
+var CREDENTIAL_REJECTED_EXIT_TOOL_USE = UNCONFIGURED_EXIT_TOOL_USE;
+var CREDENTIAL_REJECTED_EXIT_STOP_FAMILY = UNCONFIGURED_EXIT_STOP_FAMILY;
+function credentialRejectedMessage(statusCode, serviceMessage, remedy, label = "[Halfcycle]") {
+  const forbidden = statusCode === 403;
+  const statusName = forbidden ? "Forbidden" : "Unauthorized";
+  const cause = forbidden ? `this credential is not authorised for the engagement this repository is sending` : `the credential this repository is sending is not one it accepts`;
+  return `${label} GUARD CREDENTIAL REJECTED \u2014 the guard service answered and refused this credential.
+No evaluation was performed: the service returned ${statusCode} ${statusName} \u2014 ${serviceMessage}
+This is not a service outage. The guard service is up and replying; ${cause}, so this change was not checked.
+${remedy}
+`;
+}
+function emitCredentialRejected(statusCode, serviceMessage, exitCode, remedy = HOOK_REMEDY) {
+  writeSync(2, credentialRejectedMessage(statusCode, serviceMessage, remedy));
+  process.exitCode = exitCode;
+}
+function credentialRenewalFailedMessage(remedy, label = "[Halfcycle]") {
+  return `${label} This project's stored credential has expired and could not be renewed automatically, so changes in this session will not be checked.
+${remedy}
+`;
+}
+function notRunReport(notRun, label = "[Halfcycle]") {
+  if (!notRun || notRun.length === 0)
+    return "";
+  const count = notRun.length;
+  const noun = count === 1 ? "check" : "checks";
+  const lines = notRun.map((entry) => `  [NOT RUN] ${entry.patternRef}: ${entry.reason}`);
+  return [`${label} ${count} ${noun} did not run on this change:`, ...lines].join("\n");
+}
+
+// dist/ci-oidc.js
+var CI_EXCHANGE_PATH = "/auth/ci/exchange";
+var REQUEST_TIMEOUT_MS = 1e4;
+function idTokenRequestUrl(requestUrl, audience) {
+  const url2 = new URL(requestUrl);
+  url2.searchParams.set("audience", audience);
+  return url2;
+}
+async function fetchWithTimeout(fetchFn, input, init) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetchFn(input, { ...init, signal: controller.signal });
+    return { ok: true, response };
+  } catch (err) {
+    const timedOut = err instanceof Error && err.name === "AbortError";
+    return {
+      ok: false,
+      message: timedOut ? `no answer after ${REQUEST_TIMEOUT_MS}ms` : err instanceof Error ? err.message : String(err)
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function requestIdentityToken(oidc, fetchFn = globalThis.fetch) {
+  let url2;
+  try {
+    url2 = idTokenRequestUrl(oidc.requestUrl, HALFCYCLE_OIDC_AUDIENCE);
+  } catch {
+    return { ok: false, message: "the token request address this job was given is not a URL" };
+  }
+  const attempt2 = await fetchWithTimeout(fetchFn, url2.toString(), {
+    method: "GET",
+    headers: { Authorization: `Bearer ${oidc.requestToken}` }
+  });
+  if (!attempt2.ok)
+    return { ok: false, message: attempt2.message };
+  const { response } = attempt2;
+  if (!response.ok) {
+    return { ok: false, message: `the token service answered ${response.status}` };
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { ok: false, message: "the token service did not answer with JSON" };
+  }
+  const value = typeof body === "object" && body !== null ? body.value : void 0;
+  if (typeof value !== "string" || value.trim() === "") {
+    return { ok: false, message: "the token service answered without a token" };
+  }
+  return { ok: true, identityToken: value.trim() };
+}
+async function exchangeIdentityToken(controlOrigin, identityToken, fetchFn = globalThis.fetch) {
+  const attempt2 = await fetchWithTimeout(fetchFn, `${controlOrigin}${CI_EXCHANGE_PATH}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${identityToken}` }
+  });
+  if (!attempt2.ok)
+    return { ok: false, kind: "service", message: attempt2.message };
+  const { response } = attempt2;
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return {
+      ok: false,
+      kind: "contract",
+      message: "the control plane did not answer the exchange with JSON"
+    };
+  }
+  if (!response.ok) {
+    const parsed2 = wireErrorSchema.safeParse(body);
+    if (!parsed2.success) {
+      return {
+        ok: false,
+        kind: "contract",
+        message: `the control plane refused the exchange in an unreadable shape (${response.status})`
+      };
+    }
+    const decided = parsed2.data.statusCode === 401 || parsed2.data.statusCode === 403;
+    return decided ? { ok: false, kind: "refused", statusCode: parsed2.data.statusCode, message: parsed2.data.message } : { ok: false, kind: "service", message: parsed2.data.message };
+  }
+  const parsed = ciTokenExchangeResponseSchema.safeParse(body);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      kind: "contract",
+      message: `the exchange response did not match the declared shape: ${parsed.error.message}`
+    };
+  }
+  return {
+    ok: true,
+    credential: {
+      guardServiceToken: parsed.data.token,
+      guardEngagementId: parsed.data.engagementId,
+      expiresAt: parsed.data.expiresAt
+    }
+  };
+}
+async function acquireCredentialByIdentityToken(oidc, controlOrigin, fetchFn = globalThis.fetch) {
+  const minted = await requestIdentityToken(oidc, fetchFn);
+  if (!minted.ok)
+    return { ok: false, kind: "provider", message: minted.message };
+  return exchangeIdentityToken(controlOrigin, minted.identityToken, fetchFn);
+}
+function credentialExchangeFailureMessage(failure, label = "[Halfcycle CI]") {
+  switch (failure.kind) {
+    case "provider":
+      return `${label} No CI identity token \u2014 ${failure.message}.
+No evaluation was attempted. This job authenticates by asking its own runner for a signed identity token, which requires the workflow to grant:
+` + // The block and the both-lines sentence come from the runner's one wording
+      // home (T-15): this text and the never-configured remedy must never
+      // disagree on what the block is.
+      PERMISSIONS_BLOCK + `${BOTH_LINES_SENTENCE} If the workflow already has a permissions block, add \`id-token: write\` to it and leave the rest alone. Or supply the guard secrets instead.
+`;
+    case "refused":
+      return `${label} CI authentication refused (${failure.statusCode}): ${failure.message}
+This is NOT a guard violation and NOT an outage \u2014 the identity token was presented and the answer came back. Nothing was evaluated.
+`;
+    case "service":
+      return `${label} Infrastructure failure: the CI credential could not be obtained \u2014 ${failure.message}.
+This is NOT a guard violation. Fix the infrastructure issue and re-run.
+`;
+    case "contract":
+      return `${label} Infrastructure failure (contract error): ${failure.message}.
+The service answered; the suspect is this runner being older than it.
+`;
+  }
+}
+
+// dist/client.js
+var REQUEST_TIMEOUT_MS2 = 1e4;
+async function evaluate(url2, token, request, fetchFn = globalThis.fetch) {
+  return attempt(
+    url2,
+    token,
+    request,
+    fetchFn,
+    /* retry */
+    true
+  );
+}
+async function attempt(url2, token, request, fetchFn, retry) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS2);
+  let response;
+  try {
+    response = await fetchFn(`${url2}/evaluate`, {
+      method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${token}`
@@ -14841,7 +15393,7 @@ async function attempt(url2, token, request, fetchFn, retry) {
         false
       );
     }
-    const message = isTimeout ? `Guard service timed out after ${REQUEST_TIMEOUT_MS}ms` : err instanceof Error ? err.message : String(err);
+    const message = isTimeout ? `Guard service timed out after ${REQUEST_TIMEOUT_MS2}ms` : err instanceof Error ? err.message : String(err);
     return { ok: false, kind: "infra-error", message };
   }
   let body;
@@ -16170,115 +16722,11 @@ async function emitRunRecord(opts) {
   });
   await emitTelemetry(run, {
     controlTelemetryUrl: telemetryConfig.controlTelemetryUrl,
-    controlTelemetryToken: telemetryConfig.controlTelemetryToken,
+    controlTelemetryToken: opts.credential ?? telemetryConfig.controlTelemetryToken,
     guardEvalLogDir: telemetryConfig.guardEvalLogDir
   }, { warn: (msg) => process.stderr.write(msg + "\n") });
 }
 
-// dist/hook-protocol.js
-import { writeSync } from "node:fs";
-function emitBlock(reason) {
-  process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
-  process.exit(0);
-}
-function emitWarning(text) {
-  process.stdout.write(text + "\n");
-}
-function emitInfraWarning(message) {
-  process.stdout.write(`[Halfcycle] WARNING: Guard service unavailable \u2014 ${message}. Session continues (fail-open).
-`);
-}
-function emitLocalFault(message) {
-  process.stdout.write(`[Halfcycle] WARNING: Local fault \u2014 ${message}. The guard service was not contacted. Session continues (fail-open).
-`);
-}
-function emitContractFault(message) {
-  process.stdout.write(`[Halfcycle] WARNING: Guard response could not be understood \u2014 ${message}
-This is not a service outage: the guard service answered. The suspect is this repository's own installed halfcycle runner, which is out of date with what the service now sends. Update it: run "npx halfcycle" in this repository, then retry. Session continues (fail-open).
-`);
-}
-var UNCONFIGURED_EXIT_TOOL_USE = 2;
-var UNCONFIGURED_EXIT_STOP_FAMILY = 1;
-function emitNeverConfigured(missing, exitCode, reason) {
-  writeSync(2, neverConfiguredReport(missing, reason));
-  process.exitCode = exitCode;
-}
-var HOOK_REMEDY = `Fix it by running "npx halfcycle" in this repository: it may open your browser to sign in first, then writes this engagement's credentials to ~/.halfcycle \u2014 outside the repository \u2014 and the hook loads them itself.`;
-var CI_REMEDY = "This job cannot vouch for anything; supply the guard secrets to the workflow.";
-function neverConfiguredMessage(missing, remedy, label = "[Halfcycle]") {
-  return `${label} GUARD NEVER CONFIGURED \u2014 this repository has no guard coverage.
-No evaluation was attempted, because there is nothing to attempt one with: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} absent.
-This is not a service outage. It means the guard has never run here \u2014 not on this change, and not on any change before it.
-${remedy}
-`;
-}
-function notThisAccountReport(label) {
-  return `${label} This project belongs to another Halfcycle account. Halfcycle is Solo today \u2014 one person works on a project at a time \u2014 so no credential exists for this machine and none will be issued. Nothing here needs fixing; this copy simply is not checked. Ask the project's owner for view access, or \u2014 if this account is wrong \u2014 sign in as the one that owns the project and run "npx halfcycle" again.
-`;
-}
-function neverConfiguredReport(missing, reason, label = "[Halfcycle]") {
-  switch (reason) {
-    case "no-credential-yet":
-      return neverConfiguredMessage(missing, HOOK_REMEDY, label);
-    case "not-this-account":
-      return notThisAccountReport(label);
-  }
-}
-var CREDENTIAL_REJECTED_STATUSES = /* @__PURE__ */ new Set([401, 403]);
-function classifyFailure(failure) {
-  if (failure.kind === "contract-error") {
-    return {
-      kind: "contract",
-      message: failure.message,
-      label: "contract error",
-      reason: `contract error: ${failure.message}`
-    };
-  }
-  if (failure.kind === "wire-error" && CREDENTIAL_REJECTED_STATUSES.has(failure.statusCode)) {
-    const label = `credential rejected (${failure.statusCode})`;
-    return {
-      kind: "credential",
-      statusCode: failure.statusCode,
-      message: failure.message,
-      label,
-      reason: `${label}: ${failure.message}`
-    };
-  }
-  return {
-    kind: "service",
-    message: failure.message,
-    // Unchanged wording for this class ON PURPOSE — a genuine outage still says
-    // exactly what it said before, and still fails open locally. This task moved
-    // ONE condition out of this branch; it did not redefine the branch.
-    label: "infrastructure failure",
-    reason: `infrastructure failure: ${failure.message}`
-  };
-}
-var CREDENTIAL_REJECTED_EXIT_TOOL_USE = UNCONFIGURED_EXIT_TOOL_USE;
-var CREDENTIAL_REJECTED_EXIT_STOP_FAMILY = UNCONFIGURED_EXIT_STOP_FAMILY;
-function credentialRejectedMessage(statusCode, serviceMessage, remedy, label = "[Halfcycle]") {
-  const forbidden = statusCode === 403;
-  const statusName = forbidden ? "Forbidden" : "Unauthorized";
-  const cause = forbidden ? `this credential is not authorised for the engagement this repository is sending` : `the credential this repository is sending is not one it accepts`;
-  return `${label} GUARD CREDENTIAL REJECTED \u2014 the guard service answered and refused this credential.
-No evaluation was performed: the service returned ${statusCode} ${statusName} \u2014 ${serviceMessage}
-This is not a service outage. The guard service is up and replying; ${cause}, so this change was not checked.
-${remedy}
-`;
-}
-function emitCredentialRejected(statusCode, serviceMessage, exitCode) {
-  writeSync(2, credentialRejectedMessage(statusCode, serviceMessage, HOOK_REMEDY));
-  process.exitCode = exitCode;
-}
-function notRunReport(notRun, label = "[Halfcycle]") {
-  if (!notRun || notRun.length === 0)
-    return "";
-  const count = notRun.length;
-  const noun = count === 1 ? "check" : "checks";
-  const lines = notRun.map((entry) => `  [NOT RUN] ${entry.patternRef}: ${entry.reason}`);
-  return [`${label} ${count} ${noun} did not run on this change:`, ...lines].join("\n");
-}
-
 // dist/ci.js
 async function runCi() {
   const repoRootResult = getRepoRoot(process.cwd());
@@ -16320,12 +16768,37 @@ async function runCi() {
   const context = loadChangeSetContext(repoRoot);
   const changeSet = buildChangeSet(fileDiffEntries, { ...context, excerpts: readExcerptConfig() });
   const configResult = readConfig();
+  if (!configResult.config) {
+    const oidc = readActionsOidcEnv();
+    if (oidc) {
+      const acquired = await acquireCredentialByIdentityToken(oidc, readControlOrigin().origin);
+      if (!acquired.ok) {
+        await emitRunRecord({
+          runType: "ci",
+          outcome: acquired.kind === "contract" ? "contract-error" : "infra-error",
+          failureReason: `ci credential: ${acquired.kind}: ${acquired.message}`,
+          changeSet
+        });
+        process.stderr.write(credentialExchangeFailureMessage(acquired));
+        return 1;
+      }
+      return await evaluateAndAct({
+        guardServiceUrl: readGuardOrigin().origin,
+        guardServiceToken: acquired.credential.guardServiceToken,
+        guardEngagementId: acquired.credential.guardEngagementId,
+        changeSet
+      });
+    }
+  }
   if (!configResult.config) {
     await emitRunRecord({ runType: "ci", outcome: "unconfigured", changeSet });
     process.stderr.write(neverConfiguredMessage(configResult.missing, CI_REMEDY, "[Halfcycle CI]"));
     return 1;
   }
-  const { guardServiceUrl, guardServiceToken, guardEngagementId } = configResult.config;
+  return await evaluateAndAct({ ...configResult.config, changeSet });
+}
+async function evaluateAndAct(args2) {
+  const { guardServiceUrl, guardServiceToken, guardEngagementId, changeSet } = args2;
   const clientResult = await evaluate(guardServiceUrl, guardServiceToken, {
     engagementId: guardEngagementId,
     changeSet,
@@ -16368,7 +16841,23 @@ async function runCi() {
   });
   await emitTelemetry(run, {
     controlTelemetryUrl: telemetryConfig.controlTelemetryUrl,
-    controlTelemetryToken: telemetryConfig.controlTelemetryToken,
+    // THE CREDENTIAL THIS RUN EVALUATED WITH — the argument, never a second read of
+    // the environment. `readTelemetryConfig().controlTelemetryToken` is the stored
+    // `GUARD_SERVICE_TOKEN`, and on the stored path it is the SAME `process.env` read
+    // this argument came from, so nothing changes there.
+    //
+    // **IT IS NOT `telemetryConfig.controlTelemetryToken ?? guardServiceToken`, AND
+    // THE DIFFERENCE IS A HALF-MIGRATED WORKFLOW** (R-09 blocker). That `??` is
+    // environment-first, so the stored variable wins wherever it is set — including
+    // on the identity-token path, which is reached when `readConfig()` returned
+    // `null`, i.e. when the pair is PARTIAL as well as when it is absent. A workflow
+    // with `GUARD_ENGAGEMENT_ID` removed and `GUARD_SERVICE_TOKEN` still injected —
+    // one of two workflow files edited, an org secret still mapped, one matrix leg
+    // missed — would evaluate correctly against the engagement the plane resolved and
+    // then POST its run record with the stale token, which `bindEngagement` refuses
+    // 403. Every run record from that workflow is lost, and the only trace names a
+    // status rather than the wrong credential.
+    controlTelemetryToken: guardServiceToken,
     // Per-engagement log dir from HALFCYCLE_GUARD_EVAL_LOG_DIR (E1-T-02, #61).
     guardEvalLogDir: telemetryConfig.guardEvalLogDir
   }, {
@@ -16413,6 +16902,196 @@ function actOnEnvelope(envelope) {
   }
 }
 
+// dist/credential-store.js
+import { chmodSync, readFileSync as readFileSync5, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2, realpathSync } from "node:fs";
+import { homedir as homedir2, platform } from "node:os";
+import { dirname as dirname3, join as join5 } from "node:path";
+var REFRESHED_TOKEN_KEYS = ["HALFCYCLE_TOKEN", "GUARD_SERVICE_TOKEN"];
+var TOKEN_READ_KEY = "GUARD_SERVICE_TOKEN";
+var UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function composeEngagementEnvPath(engagementId, home) {
+  return join5(home ?? homedir2(), HALFCYCLE_DIR_NAME, ENGAGEMENTS_DIR_NAME, engagementId, ENGAGEMENT_ENV_FILENAME);
+}
+function readAccountCredential(controlOrigin, home) {
+  let raw;
+  try {
+    raw = readFileSync5(join5(home ?? homedir2(), HALFCYCLE_DIR_NAME, ACCOUNT_STORE_FILENAME), "utf-8");
+  } catch {
+    return void 0;
+  }
+  const entry = parseAccountStoreText(raw).accounts[normaliseOrigin(controlOrigin)];
+  if (!entry || typeof entry.credential !== "string" || entry.credential.trim() === "") {
+    return void 0;
+  }
+  return entry.credential;
+}
+function readStoredEngagementToken(envFilePath) {
+  let raw;
+  try {
+    raw = readFileSync5(envFilePath, "utf-8");
+  } catch {
+    return void 0;
+  }
+  const value = parseEnvText(raw)[TOKEN_READ_KEY];
+  return value && value.trim() !== "" ? value : void 0;
+}
+function writeRefreshedToken(opts) {
+  if (!UUID_SHAPE.test(opts.engagementId)) {
+    return { written: false, reason: "the engagement this session names is not one this store can be keyed by" };
+  }
+  let declaredReal;
+  let composedReal;
+  try {
+    declaredReal = realpathSync(opts.envFilePath);
+    composedReal = realpathSync(composeEngagementEnvPath(opts.engagementId, opts.home));
+  } catch {
+    return { written: false, reason: "the credential file named for this session could not be resolved on disk" };
+  }
+  if (declaredReal !== composedReal) {
+    return {
+      written: false,
+      reason: "the credential file named for this session is not this engagement's own credential file"
+    };
+  }
+  let existing;
+  try {
+    existing = readFileSync5(declaredReal, "utf-8");
+  } catch {
+    existing = null;
+  }
+  const body = reconcileEnvText(existing, { HALFCYCLE_TOKEN: opts.token, GUARD_SERVICE_TOKEN: opts.token }, REFRESHED_TOKEN_KEYS);
+  const temp = join5(dirname3(declaredReal), `.${ENGAGEMENT_ENV_FILENAME}.${process.pid}.tmp`);
+  try {
+    writeFileSync2(temp, body, { mode: 384 });
+    if (platform() !== "win32")
+      chmodSync(temp, 384);
+    renameSync2(temp, declaredReal);
+  } catch (err) {
+    try {
+      unlinkSync2(temp);
+    } catch {
+    }
+    return {
+      written: false,
+      reason: `the credential file could not be replaced: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  return { written: true };
+}
+
+// dist/credential-refresh.js
+var CONTROL_TIMEOUT_MS = 5e3;
+var UNAUTHORIZED = 401;
+async function probeAccount(controlOrigin, credential, fetchFn = globalThis.fetch) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CONTROL_TIMEOUT_MS);
+  try {
+    const response = await fetchFn(`${controlOrigin}/account`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${credential}` },
+      signal: controller.signal
+    });
+    return { reached: true, status: response.status };
+  } catch {
+    return { reached: false };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function mintThroughJoin(controlOrigin, engagementId, accountCredential, fetchFn) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CONTROL_TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetchFn(`${controlOrigin}/engagements/${encodeURIComponent(engagementId)}/join`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${accountCredential}`
+      },
+      body: JSON.stringify({}),
+      signal: controller.signal
+    });
+  } catch {
+    return { ok: false, remedy: UNREACHABLE_REMEDY };
+  } finally {
+    clearTimeout(timer);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    body = void 0;
+  }
+  if (!response.ok) {
+    if (response.status === UNAUTHORIZED)
+      return { ok: false, remedy: HOOK_REMEDY };
+    return { ok: false, remedy: planeSentence(body) ?? UNREADABLE_REFUSAL_REMEDY };
+  }
+  const parsed = engagementCredentialResponseSchema.safeParse(body);
+  if (!parsed.success)
+    return { ok: false, remedy: UNREADABLE_MINT_REMEDY };
+  return { ok: true, token: parsed.data.sessionToken, source: "mint" };
+}
+function planeSentence(body) {
+  if (typeof body !== "object" || body === null)
+    return void 0;
+  const message = body.message;
+  return typeof message === "string" && message.trim() !== "" ? message : void 0;
+}
+var UNREACHABLE_REMEDY = "The Halfcycle service could not be reached to renew this credential. Nothing is wrong with this repository; the next change will try again.";
+var UNREADABLE_REFUSAL_REMEDY = "The Halfcycle service declined to renew this credential and gave no reason this version could read.";
+var UNREADABLE_MINT_REMEDY = 'The Halfcycle service answered with a credential this version could not read. Update the installed Halfcycle runner: run "npx halfcycle" in this repository.';
+async function refreshEngagementCredential(opts) {
+  const envFilePath = readEnvFilePath();
+  if (!envFilePath)
+    return { ok: false, remedy: HOOK_REMEDY };
+  const stored = readStoredEngagementToken(envFilePath);
+  if (stored !== void 0 && stored !== opts.refusedToken) {
+    return { ok: true, token: stored, source: "disk" };
+  }
+  const controlOrigin = readControlOrigin().origin;
+  const accountCredential = readAccountCredential(controlOrigin, opts.home);
+  if (!accountCredential)
+    return { ok: false, remedy: HOOK_REMEDY };
+  const minted = await mintThroughJoin(controlOrigin, opts.engagementId, accountCredential, opts.fetchFn ?? globalThis.fetch);
+  if (!minted.ok)
+    return minted;
+  const write = writeRefreshedToken({
+    envFilePath,
+    engagementId: opts.engagementId,
+    token: minted.token,
+    home: opts.home
+  });
+  if (!write.written) {
+    const warn = opts.warn ?? ((message) => process.stderr.write(message));
+    warn(`[Halfcycle] This engagement's credential was renewed for this run only \u2014 ${write.reason}.
+`);
+  }
+  return minted;
+}
+async function evaluateWithRefresh(opts) {
+  const fetchFn = opts.fetchFn ?? globalThis.fetch;
+  const first = await evaluate(opts.guardServiceUrl, opts.token, opts.request, fetchFn);
+  if (first.ok)
+    return { result: first, token: opts.token, remedy: HOOK_REMEDY };
+  const failure = classifyFailure(first);
+  if (failure.kind !== "credential" || failure.statusCode !== UNAUTHORIZED) {
+    return { result: first, token: opts.token, remedy: HOOK_REMEDY };
+  }
+  const refreshed = await refreshEngagementCredential({
+    engagementId: opts.engagementId,
+    refusedToken: opts.token,
+    fetchFn,
+    home: opts.home,
+    warn: opts.warn
+  });
+  if (!refreshed.ok)
+    return { result: first, token: opts.token, remedy: refreshed.remedy };
+  const retry = await evaluate(opts.guardServiceUrl, refreshed.token, opts.request, fetchFn);
+  return { result: retry, token: refreshed.token, remedy: HOOK_REMEDY };
+}
+
 // dist/hooks/post-tool-use.js
 var HANDLED_EDIT_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
 async function runPostToolUse() {
@@ -16451,11 +17130,17 @@ async function runPostToolUse() {
     return;
   }
   const { guardServiceUrl, guardServiceToken, guardEngagementId } = configResult.config;
-  const clientResult = await evaluate(guardServiceUrl, guardServiceToken, {
+  const evaluation = await evaluateWithRefresh({
+    guardServiceUrl,
+    token: guardServiceToken,
     engagementId: guardEngagementId,
-    changeSet,
-    clientCapabilities: deriveClientCapabilities(changeSet)
+    request: {
+      engagementId: guardEngagementId,
+      changeSet,
+      clientCapabilities: deriveClientCapabilities(changeSet)
+    }
   });
+  const clientResult = evaluation.result;
   if (!clientResult.ok) {
     const failure = classifyFailure(clientResult);
     await emitRunRecord({
@@ -16463,10 +17148,19 @@ async function runPostToolUse() {
       runType: "hook",
       outcome: outcomeForClientFailure(clientResult.kind),
       failureReason: failure.reason,
-      changeSet
+      changeSet,
+      credential: evaluation.token
     });
     if (failure.kind === "credential") {
-      emitCredentialRejected(failure.statusCode, failure.message, CREDENTIAL_REJECTED_EXIT_TOOL_USE);
+      emitCredentialRejected(
+        failure.statusCode,
+        failure.message,
+        CREDENTIAL_REJECTED_EXIT_TOOL_USE,
+        // The remedy the renewal attempt earned: the sign-in when the account
+        // credential is the thing that was refused, and otherwise the plane's own
+        // sentence about why it would not mint.
+        evaluation.remedy
+      );
       return;
     }
     if (failure.kind === "contract") {
@@ -16489,7 +17183,13 @@ async function runPostToolUse() {
   });
   await emitTelemetry(run, {
     controlTelemetryUrl: telemetryConfig.controlTelemetryUrl,
-    controlTelemetryToken: telemetryConfig.controlTelemetryToken,
+    // THE CREDENTIAL IN FORCE, NOT THE ONE IN THE ENVIRONMENT (T-08,
+    // credential-lifecycle). `readTelemetryConfig` reads the bearer off
+    // `process.env` after the evaluation, and a renewal does not write there — so
+    // taking its value on a run that just recovered would present the credential
+    // the plane had already refused and drop the record with a 401, silently,
+    // because telemetry is best-effort.
+    controlTelemetryToken: evaluation.token,
     // Per-engagement log dir from HALFCYCLE_GUARD_EVAL_LOG_DIR (E1-T-02, #61).
     guardEvalLogDir: telemetryConfig.guardEvalLogDir
   }, {
@@ -16528,9 +17228,9 @@ function readStdin() {
 
 // dist/hooks/marker.js
 import { createHash } from "node:crypto";
-import { existsSync as existsSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2, readdirSync as readdirSync3, statSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync3, unlinkSync as unlinkSync3, readdirSync as readdirSync3, statSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 var MARKER_TTL_MS = 24 * 60 * 60 * 1e3;
 var MARKER_PREFIX = "halfcycle-session-";
 var MARKER_SUFFIX = ".ref";
@@ -16548,19 +17248,19 @@ function markerFileName(repoRoot, sessionId) {
   return `${MARKER_PREFIX}${key}${MARKER_SUFFIX}`;
 }
 function markerPath(repoRoot, sessionId) {
-  return join5(markerDir(), markerFileName(repoRoot, sessionId));
+  return join6(markerDir(), markerFileName(repoRoot, sessionId));
 }
 function dedupePath(repoRoot, sessionId) {
   const hash2 = repoHash(repoRoot);
   const key = sessionId && sessionId.length > 0 ? `${hash2}-${sessionId}` : hash2;
-  return join5(markerDir(), `${MARKER_PREFIX}${key}${DEDUPE_SUFFIX}`);
+  return join6(markerDir(), `${MARKER_PREFIX}${key}${DEDUPE_SUFFIX}`);
 }
 function readMarker(repoRoot, sessionId) {
   const path = markerPath(repoRoot, sessionId);
   if (!existsSync2(path))
     return null;
   try {
-    return readFileSync5(path, "utf-8").trim() || null;
+    return readFileSync6(path, "utf-8").trim() || null;
   } catch {
     return null;
   }
@@ -16569,7 +17269,7 @@ function deleteMarker(repoRoot, sessionId) {
   for (const path of [markerPath(repoRoot, sessionId), dedupePath(repoRoot, sessionId)]) {
     try {
       if (existsSync2(path))
-        unlinkSync2(path);
+        unlinkSync3(path);
     } catch {
     }
   }
@@ -16579,7 +17279,7 @@ function readDedupe(repoRoot, sessionId) {
   if (!existsSync2(path))
     return null;
   try {
-    const parsed = JSON.parse(readFileSync5(path, "utf-8"));
+    const parsed = JSON.parse(readFileSync6(path, "utf-8"));
     if (typeof parsed === "object" && parsed !== null && typeof parsed.base === "string" && typeof parsed.digest === "string") {
       return parsed;
     }
@@ -16590,7 +17290,7 @@ function readDedupe(repoRoot, sessionId) {
 }
 function writeDedupe(repoRoot, sessionId, state) {
   try {
-    writeFileSync2(dedupePath(repoRoot, sessionId), JSON.stringify(state), "utf-8");
+    writeFileSync3(dedupePath(repoRoot, sessionId), JSON.stringify(state), "utf-8");
   } catch {
   }
 }
@@ -16621,10 +17321,10 @@ function orphanSweep(repoRoot, refKnown, keepSessionId, now = Date.now()) {
       continue;
     if (name === keepName)
       continue;
-    const full = join5(dir, name);
+    const full = join6(dir, name);
     let unusable = false;
     try {
-      const ref = readFileSync5(full, "utf-8").trim();
+      const ref = readFileSync6(full, "utf-8").trim();
       if (!ref || !refKnown(ref))
         unusable = true;
     } catch {
@@ -16717,11 +17417,17 @@ async function runSessionDiff(input, kind) {
     return;
   }
   const { guardServiceUrl, guardServiceToken, guardEngagementId } = configResult.config;
-  const clientResult = await evaluate(guardServiceUrl, guardServiceToken, {
+  const evaluation = await evaluateWithRefresh({
+    guardServiceUrl,
+    token: guardServiceToken,
     engagementId: guardEngagementId,
-    changeSet,
-    clientCapabilities: deriveClientCapabilities(changeSet)
+    request: {
+      engagementId: guardEngagementId,
+      changeSet,
+      clientCapabilities: deriveClientCapabilities(changeSet)
+    }
   });
+  const clientResult = evaluation.result;
   if (!clientResult.ok) {
     const failure = classifyFailure(clientResult);
     await emitRunRecord({
@@ -16730,10 +17436,19 @@ async function runSessionDiff(input, kind) {
       outcome: outcomeForClientFailure(clientResult.kind),
       failureReason: failure.reason,
       changeSet,
-      diffBase
+      diffBase,
+      credential: evaluation.token
     });
     if (failure.kind === "credential") {
-      emitCredentialRejected(failure.statusCode, failure.message, CREDENTIAL_REJECTED_EXIT_STOP_FAMILY);
+      emitCredentialRejected(
+        failure.statusCode,
+        failure.message,
+        CREDENTIAL_REJECTED_EXIT_STOP_FAMILY,
+        // The remedy the renewal attempt earned: the sign-in when the account
+        // credential is what was refused, and otherwise the plane's own sentence
+        // about why it would not mint.
+        evaluation.remedy
+      );
       return;
     }
     if (failure.kind === "contract") {
@@ -16755,7 +17470,12 @@ async function runSessionDiff(input, kind) {
   });
   await emitTelemetry(run, {
     controlTelemetryUrl: telemetryConfig.controlTelemetryUrl,
-    controlTelemetryToken: telemetryConfig.controlTelemetryToken,
+    // THE CREDENTIAL IN FORCE, NOT THE ONE IN THE ENVIRONMENT (T-08,
+    // credential-lifecycle). The telemetry bearer is otherwise read off
+    // `process.env` after the evaluation, which a renewal does not write to — so a
+    // run that just recovered would present the refused credential and drop its
+    // record with a 401, silently, because telemetry is best-effort.
+    controlTelemetryToken: evaluation.token,
     guardEvalLogDir: telemetryConfig.guardEvalLogDir
   }, {
     warn: (msg) => process.stderr.write(msg + "\n")
@@ -16836,17 +17556,17 @@ async function runStop() {
 }
 
 // dist/resolve-engagement.js
-import { existsSync as existsSync3, readFileSync as readFileSync6, realpathSync } from "node:fs";
-import { join as join6, sep as sep2 } from "node:path";
-import { homedir as homedir2 } from "node:os";
+import { existsSync as existsSync3, readFileSync as readFileSync7, realpathSync as realpathSync2 } from "node:fs";
+import { join as join7, sep as sep2 } from "node:path";
+import { homedir as homedir3 } from "node:os";
 function defaultRegistryPath() {
-  return join6(homedir2(), ".halfcycle", "registry.json");
+  return join7(homedir3(), ".halfcycle", "registry.json");
 }
 function readRegistry(registryPath = defaultRegistryPath()) {
   if (!existsSync3(registryPath))
     return {};
   try {
-    const parsed = JSON.parse(readFileSync6(registryPath, "utf-8"));
+    const parsed = JSON.parse(readFileSync7(registryPath, "utf-8"));
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
       return {};
     const out = {};
@@ -16861,7 +17581,7 @@ function readRegistry(registryPath = defaultRegistryPath()) {
 }
 function canonicalise(p) {
   try {
-    return realpathSync(p);
+    return realpathSync2(p);
   } catch {
     return p;
   }
@@ -16893,9 +17613,41 @@ function runResolveEngagement(cwd, registryPath) {
   return 0;
 }
 
+// dist/refresh-credential.js
+var UNAUTHORIZED2 = 401;
+async function runRefreshCredential(opts) {
+  if (readNeverConfiguredReason() === "not-this-account")
+    return 0;
+  if (!readEnvFilePath())
+    return 0;
+  const configResult = readConfig();
+  if (!configResult.config)
+    return 0;
+  const { guardServiceToken, guardEngagementId } = configResult.config;
+  const controlOrigin = readControlOrigin().origin;
+  const fetchFn = opts?.fetchFn ?? globalThis.fetch;
+  const accountCredential = readAccountCredential(controlOrigin, opts?.home);
+  if (accountCredential)
+    await probeAccount(controlOrigin, accountCredential, fetchFn);
+  const probe = await probeAccount(controlOrigin, guardServiceToken, fetchFn);
+  if (!probe.reached || probe.status !== UNAUTHORIZED2)
+    return 0;
+  const refreshed = await refreshEngagementCredential({
+    engagementId: guardEngagementId,
+    refusedToken: guardServiceToken,
+    fetchFn,
+    home: opts?.home
+  });
+  if (!refreshed.ok) {
+    const write = opts?.write ?? ((text) => process.stdout.write(text));
+    write(credentialRenewalFailedMessage(refreshed.remedy));
+  }
+  return 0;
+}
+
 // dist/capture.js
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync4 } from "node:fs";
-import { dirname as dirname3 } from "node:path";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3, existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname4 } from "node:path";
 function runCapture(provider, endpoint, opts = {}) {
   const repoRoot = opts.repoRoot ?? process.cwd();
   const raw = opts.input ?? readInputFile(opts.fromFile);
@@ -16930,8 +17682,8 @@ function runCapture(provider, endpoint, opts = {}) {
   const fixture = fixturePath(repoRoot, provider, slug);
   const manifestFile = manifestPath(repoRoot);
   try {
-    mkdirSync3(dirname3(fixture), { recursive: true });
-    writeFileSync3(fixture, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+    mkdirSync3(dirname4(fixture), { recursive: true });
+    writeFileSync4(fixture, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { ok: false, kind: "write-failed", message: `could not write fixture: ${msg}` };
@@ -16962,7 +17714,7 @@ function readInputFile(fromFile) {
   if (!fromFile)
     return void 0;
   try {
-    return readFileSync7(fromFile, "utf-8");
+    return readFileSync8(fromFile, "utf-8");
   } catch {
     return void 0;
   }
@@ -16981,6 +17733,11 @@ async function main() {
     process.exit(code);
     return;
   }
+  if (cmd === "refresh-credential") {
+    const code = await runRefreshCredential();
+    process.exit(code);
+    return;
+  }
   if (cmd === "resolve-engagement") {
     const cwd = sub ?? process.cwd();
     const code = runResolveEngagement(cwd);
@@ -17045,6 +17802,7 @@ Commit the fixture; the next guard evaluation of this endpoint will pass.
          halfcycle-runner hook post-tool-use
          halfcycle-runner hook stop
          halfcycle-runner hook subagent-stop
+         halfcycle-runner refresh-credential
          halfcycle-runner resolve-engagement <cwd>
          halfcycle-runner capture <provider> <endpoint> [--from <file>]
 `);