halfcycle 0.3.23 → 0.3.25

package/dist/index.js

@@ -23,6 +23,89 @@ 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 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;
+}
+
 // ../events/dist/result.js
 var firedGuardSchema = z2.object({
   guardId: z2.string(),
@@ -83,7 +166,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",
@@ -137,16 +220,184 @@ var guardEvalRunSchema = z3.object({
   }
 });
 
-// ../events/dist/crew.js
+// ../events/dist/state.js
 import { z as z4 } from "zod";
-var crewGroupSchema = z4.enum(["builder", "reviewer", "always-on"]);
-var crewTierSchema = z4.enum(["deep", "standard", "fast"]);
+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 STATE_RECORD_FORMAT = "halfcycle-state-record/v1";
+var stepIdSchema = z4.string().regex(/^(l[0-5](-l[0-5])?|xl)\.[a-z0-9-]+$/);
+var methodVersionSchema = z4.string().regex(/^\d+\.\d+\.\d+$/);
+var anchorPathRegex = /^(?!\/)(?!.*#)(?!method\/)(?!(.*\/)?docs\/method\/).+$/;
+var recordKindSchema = z4.enum(["artefact", "step-run", "gate", "intervention"]);
+var methodLayerSchema = z4.enum(["l0", "l1", "l2", "l3", "l3-l4", "l4", "l5", "xl"]);
+var evidenceKindSchema = z4.enum(["anchor", "diff", "repro", "question-answer", "no-op"]);
+var declarableEvidenceKindSchema = z4.enum(["anchor", "diff", "repro", "question-answer"]);
+var dispositionSchema = z4.enum([
+  "prevented",
+  "corrected-in-spec",
+  "corrected-in-scope",
+  "blocked-in-code",
+  "flagged",
+  "auto-fixed",
+  "surfaced",
+  "filed-forward"
+]);
+var mechanismSchema = z4.enum(["guard", "verdict", "served-step", "method-step"]);
+var artefactStateSchema = z4.enum(["created", "updated"]);
+var QUALIFIED_OUTCOMES = ["declined", "parked"];
+var qualifiedOutcomeSchema = z4.enum(QUALIFIED_OUTCOMES);
+function isQualifiedOutcome(outcome) {
+  return QUALIFIED_OUTCOMES.includes(outcome);
+}
+var runOutcomeSchema = z4.enum([
+  "completed",
+  "attempted-failed",
+  ...QUALIFIED_OUTCOMES
+]);
+var gateKindSchema = z4.enum(["approval", "mechanical"]);
+var gateVerdictSchema = z4.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 = z4.object({
+  kind: z4.literal("anchor"),
+  path: z4.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: z4.number().optional()
+}).strict();
+var diffEvidenceSchema = z4.object({
+  kind: z4.literal("diff"),
+  ref: z4.string()
+}).strict();
+var reproEvidenceSchema = z4.object({
+  kind: z4.literal("repro"),
+  steps: z4.string().max(2e3)
+}).strict();
+var questionAnswerEvidenceSchema = z4.object({
+  kind: z4.literal("question-answer"),
+  question: z4.string().max(2e3),
+  before: z4.string().max(2e3),
+  after: z4.string().max(2e3)
+}).strict();
+var noOpEvidenceSchema = z4.object({
+  kind: z4.literal("no-op"),
+  inspected: z4.string().max(2e3),
+  unchangedBecause: z4.string().max(2e3)
+}).strict();
+var evidenceSchema = z4.discriminatedUnion("kind", [
+  anchorEvidenceSchema,
+  diffEvidenceSchema,
+  reproEvidenceSchema,
+  questionAnswerEvidenceSchema,
+  noOpEvidenceSchema
+]);
+var stateRecordEnvelopeSchema = z4.object({
+  format: z4.literal(STATE_RECORD_FORMAT),
+  recordKind: recordKindSchema,
+  recordId: z4.string().uuid(),
+  methodVersion: methodVersionSchema,
+  engagementId: z4.string(),
+  stepId: stepIdSchema,
+  // Immutable: names when the thing happened, never when a later disposition
+  // moved.
+  occurredAt: utcIso86012,
+  // 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: utcIso86012,
+  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: z4.string().optional()
+});
+var artefactRefSchema = z4.object({
+  name: z4.string(),
+  parent: z4.string()
+}).strict();
+var artefactRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z4.literal("artefact"),
+  artefactRef: artefactRefSchema,
+  // Some layer wrote it, by construction — an empty array is not a legitimate
+  // state, so the schema says so.
+  writtenByLayers: z4.array(methodLayerSchema).min(1),
+  state: artefactStateSchema
+}).strict();
+var stepRunRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z4.literal("step-run"),
+  runOutcome: runOutcomeSchema,
+  failureReason: z4.string().optional(),
+  outcomeReason: z4.string().max(2e3).optional()
+}).strict().superRefine((rec, ctx) => {
+  if (rec.runOutcome === "attempted-failed" && rec.failureReason === void 0) {
+    ctx.addIssue({
+      code: z4.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: z4.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: z4.ZodIssueCode.custom, path: ["outcomeReason"], ...issue });
+  }
+});
+var gateRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z4.literal("gate"),
+  gateKind: gateKindSchema,
+  verdict: gateVerdictSchema,
+  actor: z4.string(),
+  outcomeReason: z4.string().max(2e3).optional()
+}).strict().superRefine((rec, ctx) => {
+  const issue = outcomeReasonIssue(rec.verdict, rec.outcomeReason);
+  if (issue) {
+    ctx.addIssue({ code: z4.ZodIssueCode.custom, path: ["outcomeReason"], ...issue });
+  }
+});
+var interventionRecordSchema = stateRecordEnvelopeSchema.extend({
+  recordKind: z4.literal("intervention"),
+  layer: methodLayerSchema,
+  mechanism: mechanismSchema,
+  severity: severitySchema,
+  disposition: dispositionSchema,
+  summary: z4.string().max(2e3)
+}).strict();
+var stateRecordSchema = z4.discriminatedUnion("recordKind", [
+  artefactRecordSchema,
+  stepRunRecordSchema,
+  gateRecordSchema,
+  interventionRecordSchema
+]);
+
+// ../events/dist/crew.js
+import { z as z5 } from "zod";
+var crewGroupSchema = z5.enum(["builder", "reviewer", "always-on"]);
+var crewTierSchema = z5.enum(["deep", "standard", "fast"]);
 var CREW_DISCIPLINE_MAX = 64;
-var crewFaceHeadSchema = z4.enum(["sq", "sqr", "rnd", "dome", "hex"]);
-var crewFaceAntennaSchema = z4.enum(["none", "stalk", "twin", "dish"]);
-var crewFaceEyesSchema = z4.enum(["dots", "bars", "visor", "cyclops"]);
-var crewFaceMouthSchema = z4.enum(["line", "grid", "dots", "wave"]);
-var crewFaceSchema = z4.object({
+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({
   // 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,
@@ -157,17 +408,17 @@ var crewFaceSchema = z4.object({
   // The mouth.
   mouth: crewFaceMouthSchema,
   // Whether this member is drawn with ears.
-  ears: z4.boolean()
+  ears: z5.boolean()
 }).strict();
-var crewMemberSchema = z4.object({
+var crewMemberSchema = z5.object({
   // The agent's name. The same twenty-one on every project, so a name is a
   // vocabulary a returning client already knows.
-  callsign: z4.string().min(1).max(32),
+  callsign: z5.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: z4.string().min(1).max(CREW_DISCIPLINE_MAX),
+  discipline: z5.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,
@@ -392,6 +643,21 @@ function describeIdentity(identity) {
   return `(a ${typeof identity})`;
 }
 
+// ../events/dist/credential-wire.js
+import { z as z6 } from "zod";
+var engagementCredentialResponseSchema = z6.object({
+  engagementId: z6.string(),
+  sessionToken: z6.string(),
+  mcpUrl: z6.string(),
+  guardUrl: z6.string(),
+  controlTelemetryUrl: z6.string()
+}).strict();
+var ciTokenExchangeResponseSchema = z6.object({
+  token: z6.string(),
+  expiresAt: utcIso86012,
+  engagementId: z6.string()
+}).strict();
+
 // dist/engagement-credential.js
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { platform as platform2 } from "node:os";
@@ -401,12 +667,13 @@ import { join as join2 } from "node:path";
 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);
 }
 
 // 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);
@@ -414,7 +681,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";
 var GUARD_ENV_KEYS = [
   "GUARD_SERVICE_URL",
   "GUARD_SERVICE_TOKEN",
@@ -429,82 +695,8 @@ var ENGAGEMENT_ENV_KEYS = [
   ...GUARD_ENV_KEYS,
   "CONTROL_TELEMETRY_URL"
 ];
-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 {
@@ -522,7 +714,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";
   mkdirSync(dir, { recursive: true, mode: 448 });
@@ -548,7 +740,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
@@ -579,10 +771,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
@@ -781,7 +973,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",
@@ -930,6 +1122,15 @@ function generateSettingsJson() {
               timeout: 5
             }
           ]
+        },
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "bash ./.claude/hooks/guard-runner.sh refresh-credential",
+              timeout: 10
+            }
+          ]
         }
       ],
       UserPromptSubmit: [
@@ -999,9 +1200,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.
@@ -1016,6 +1217,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
@@ -1202,19 +1413,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
@@ -1225,6 +1453,9 @@ function generateCiStanza() {
 #
 # halfcycle-guard-ci:
 #   runs-on: ubuntu-latest
+#   permissions:
+#     contents: read
+#     id-token: write
 #   steps:
 #     - uses: actions/checkout@v4
 #       with:
@@ -1236,20 +1467,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
@@ -1743,6 +1969,12 @@ async function createEngagement(baseUrl, name, credential, derivedName) {
     { action: "Create-engagement", nothingHappened: "No engagement was created", route: "POST /engagements" }
   );
 }
+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;
@@ -1767,7 +1999,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);
   }
@@ -1786,6 +2020,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,
@@ -1831,7 +2075,7 @@ import { existsSync as existsSync4, lstatSync, mkdirSync as mkdirSync4, readFile
 import { dirname as dirname3, join as join6, posix } from "node:path";
 var DECLARED_ROOT_FILES = ["CLAUDE.md", "AGENTS.md", "ENGAGEMENT.md"];
 var DECLARED_DIR_PREFIX = "docs";
-var RESERVED_MIRROR_PATH = "docs/method";
+var RESERVED_METHOD_PATH = "docs/method";
 var STEP_ID_GRAMMAR = /\b(?:l[0-5](?:-l[0-5])?|xl)\.[a-z0-9-]+/i;
 var STEP_ANNOTATION = /<!--\s*step:/i;
 var ANCHOR_DECLARATION = /<!--\s*anchor:/i;
@@ -1858,8 +2102,8 @@ function assertWritable(relPath) {
   if (path.split("/").includes("..")) {
     throw new Error(`[halfcycle setup] Refusing to write "${relPath}": a path may not climb out of the repository.`);
   }
-  if (isUnderIgnoringCase(foldWin32Canonicalisation(path), RESERVED_MIRROR_PATH)) {
-    throw new Error(`[halfcycle setup] Refusing to write "${relPath}": ${RESERVED_MIRROR_PATH}/ is reserved and is never created in a project repository. The method is served per step and never installed (INV-016).`);
+  if (isUnderIgnoringCase(foldWin32Canonicalisation(path), RESERVED_METHOD_PATH)) {
+    throw new Error(`[halfcycle setup] Refusing to write "${relPath}": ${RESERVED_METHOD_PATH}/ is reserved and is never created in a project repository. The method is served per step and never installed.`);
   }
   const declared = DECLARED_ROOT_FILES.includes(path) || isUnder(path, DECLARED_DIR_PREFIX);
   if (!declared) {
@@ -1869,7 +2113,7 @@ function assertWritable(relPath) {
 function assertContentCarriesNoMethodStructure(relPath, content) {
   const carried = STEP_ID_GRAMMAR.test(content) && "a method step identifier" || STEP_ANNOTATION.test(content) && "a method step annotation" || ANCHOR_DECLARATION.test(content) && "a method anchor declaration, so this is corpus text";
   if (carried) {
-    throw new Error(`[halfcycle setup] Refusing to write "${relPath}": the content carries ${carried}. What a step directs is executed, never transcribed into the repository (INV-016).`);
+    throw new Error(`[halfcycle setup] Refusing to write "${relPath}": the content carries ${carried}. What a step directs is executed, never transcribed into the repository.`);
   }
 }
 function assertUsableHeading(relPath, heading) {
@@ -2419,7 +2663,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}`,
@@ -2439,7 +2683,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})`,
     "",
@@ -2451,7 +2695,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");