halfcycle 0.3.24 → 0.3.26

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "description": "Halfcycle Method bundle — resolution-stub slash commands, remote method-delivery registration, and governance-hook wiring for a Halfcycle engagement repo. It ships NO worker role files: a project's roles are authored from that project's own recorded decisions at orchestration kickoff (FX-2, W3-F-27).",
   "commands": [
     {

package/bin/bin.bundle.mjs

@@ -15111,6 +15111,128 @@ var ciTokenExchangeResponseSchema = external_exports.object({
   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_CANNOT_PROVE_PROJECT = "has no way to prove which project it belongs to";
+var CI_REMEDY_LEAD = "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.`;
+var CI_OLDER_SETUP = "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.";
+var CI_REMEDY = `This job cannot vouch for anything, because it ${CI_CANNOT_PROVE_PROJECT}. ${CI_REMEDY_LEAD} ${CI_OLDER_SETUP}`;
+var NEVER_CONFIGURED_HEADLINE = "GUARD NEVER CONFIGURED";
+var NOT_A_SERVICE_OUTAGE = "This is not a service outage.";
+function neverConfiguredMessage(missing, remedy, label = "[Halfcycle]") {
+  return `${label} ${NEVER_CONFIGURED_HEADLINE} \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.
+${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 ciNeverConfiguredMessage() {
+  return `[Halfcycle CI] ${NEVER_CONFIGURED_HEADLINE} \u2014 this job ${CI_CANNOT_PROVE_PROJECT}, so it checked nothing. ${CI_REMEDY_LEAD}
+${NOT_A_SERVICE_OUTAGE} Nothing was sent: this job holds no credential and was not permitted to ask GitHub for a signed identity token. It speaks for this job on this change only \u2014 other jobs and earlier changes it did not see.
+${CI_OLDER_SETUP}
+`;
+}
+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;
@@ -15222,12 +15344,10 @@ function credentialExchangeFailureMessage(failure, label = "[Halfcycle CI]") {
     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:
-
-    permissions:
-      contents: read
-      id-token: write
-
-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. 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.
+` + // 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}
@@ -15758,7 +15878,7 @@ function parseRawSql(line) {
 }
 function parseQueryBuilder(rawLine) {
   const line = stripDiffPrefix(rawLine);
-  const m = line.match(/['"]([\w]+)['"]\s*\)\s*\.(insert|update|upsert|delete)\s*\(/i);
+  const m = line.match(/(?<!\bcreate(?:Hash|Hmac|Sign|Verify|Cipheriv|Decipheriv)\s*\([^)]*)['"]([\w]+)['"]\s*\)\s*\.(insert|update|upsert|delete)\s*\(/i);
   if (m) {
     const kind = m[2].toLowerCase();
     return { kind, table: m[1].toLowerCase(), whereColumns: [] };
@@ -16324,6 +16444,22 @@ function isCodeFile(filePath) {
   }
   return true;
 }
+var INSTALLER_OUTPUT_DIR = ".halfcycle/";
+function isInstallerOutput(relPath) {
+  const normalised = relPath.replace(/\\/g, "/");
+  return normalised === INSTALLER_OUTPUT_DIR.slice(0, -1) || normalised.startsWith(INSTALLER_OUTPUT_DIR);
+}
+function partitionInstallerOutput(files) {
+  const evaluated = [];
+  const installerOutput = [];
+  for (const file2 of files) {
+    if (isInstallerOutput(file2))
+      installerOutput.push(file2);
+    else
+      evaluated.push(file2);
+  }
+  return { evaluated, installerOutput };
+}
 function buildChangeSet(files, context = {}) {
   const excerptConfig = context.excerpts;
   const excerptsEnabled = excerptConfig?.enabled === true;
@@ -16613,120 +16749,13 @@ async function emitRunRecord(opts) {
   });
   await emitTelemetry(run, {
     controlTelemetryUrl: telemetryConfig.controlTelemetryUrl,
-    controlTelemetryToken: opts.credential ?? telemetryConfig.controlTelemetryToken,
+    // No bearer at all on a refused credential: `emitTelemetry` skips the POST
+    // when it has nothing to authenticate with, which is the true state here.
+    controlTelemetryToken: opts.credentialRefused ? void 0 : 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, or let it authenticate with no secret at all by granting the workflow permission to issue an id-token.";
-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.js
 async function runCi() {
   const repoRootResult = getRepoRoot(process.cwd());
@@ -16750,11 +16779,13 @@ async function runCi() {
 `);
     return 1;
   }
-  const changedFiles = changedFilesResult.value;
-  process.stdout.write(`[Halfcycle CI] Diff base ${mergeBase.slice(0, 12)} \u2014 ${describeDiffBase(diffBase)}. ${changedFiles.length} file(s) to evaluate.
+  const { evaluated: changedFiles, installerOutput } = partitionInstallerOutput(changedFilesResult.value);
+  const setAside = installerOutput.length === 1 ? ` 1 more under ${INSTALLER_OUTPUT_DIR} is Halfcycle's own file and is not evaluated.` : installerOutput.length > 1 ? ` ${installerOutput.length} more under ${INSTALLER_OUTPUT_DIR} are Halfcycle's own files and are not evaluated.` : "";
+  process.stdout.write(`[Halfcycle CI] Diff base ${mergeBase.slice(0, 12)} \u2014 ${describeDiffBase(diffBase)}. ${changedFiles.length} file(s) to evaluate.${setAside}
 `);
   if (changedFiles.length === 0) {
-    process.stdout.write(`[Halfcycle CI] No changed files against the diff base \u2014 nothing to evaluate.
+    process.stdout.write(installerOutput.length > 0 ? `[Halfcycle CI] Nothing to evaluate: every changed file is under ${INSTALLER_OUTPUT_DIR}, which Halfcycle writes itself and does not check.
+` : `[Halfcycle CI] No changed files against the diff base \u2014 nothing to evaluate.
 `);
     return 0;
   }
@@ -16792,7 +16823,7 @@ async function runCi() {
   }
   if (!configResult.config) {
     await emitRunRecord({ runType: "ci", outcome: "unconfigured", changeSet });
-    process.stderr.write(neverConfiguredMessage(configResult.missing, CI_REMEDY, "[Halfcycle CI]"));
+    process.stderr.write(ciNeverConfiguredMessage());
     return 1;
   }
   return await evaluateAndAct({ ...configResult.config, changeSet });
@@ -16811,7 +16842,8 @@ async function evaluateAndAct(args2) {
       runType: "ci",
       outcome: outcomeForClientFailure(clientResult.kind),
       failureReason: failure.reason,
-      changeSet
+      changeSet,
+      credentialRefused: failure.kind === "credential"
     });
     if (failure.kind === "credential") {
       process.stderr.write(credentialRejectedMessage(failure.statusCode, failure.message, CI_REMEDY, "[Halfcycle CI]"));
@@ -16863,13 +16895,17 @@ async function evaluateAndAct(args2) {
   }, {
     warn: (msg) => process.stderr.write(msg + "\n")
   });
-  return actOnEnvelope(clientResult.envelope);
+  return actOnEnvelope(clientResult.envelope, {
+    files: changeSet.files.length,
+    signals: changeSetDescriptorCount(changeSet)
+  });
 }
-function actOnEnvelope(envelope) {
+function actOnEnvelope(envelope, scope) {
   const notRun = notRunReport(envelope.notRun, "[Halfcycle CI]");
   if (notRun)
     process.stdout.write(notRun + "\n");
   if (envelope.guardsFired.length === 0) {
+    process.stdout.write(cleanRunSummary(envelope.explanation, scope) + "\n");
     return 0;
   }
   if (envelope.blocking) {
@@ -16901,6 +16937,13 @@ function actOnEnvelope(envelope) {
     return 0;
   }
 }
+function cleanRunSummary(verdict, scope) {
+  const files = `${scope.files} file(s) evaluated`;
+  if (scope.signals === 0) {
+    return `[Halfcycle CI] ${verdict} ${files}, 0 signals found to check \u2014 nothing in this change is of a kind the guards look at (env references, SQL writes, schema constraints, wire-bound numeric columns, marked third-party endpoints).`;
+  }
+  return `[Halfcycle CI] ${verdict} ${files}, ${scope.signals} signal(s) checked.`;
+}
 
 // dist/credential-store.js
 import { chmodSync, readFileSync as readFileSync5, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2, realpathSync } from "node:fs";
@@ -17118,6 +17161,8 @@ async function runPostToolUse() {
   const diffContent = isNotebook ? "" : getSingleFileDiff(absFilePath, repoRoot);
   const { relative: pathRelative } = await import("node:path");
   const relPath = pathRelative(repoRoot, absFilePath);
+  if (isInstallerOutput(relPath))
+    return;
   const context = loadChangeSetContext(repoRoot);
   const changeSet = buildChangeSet([{ path: relPath, diffContent }], {
     ...context,
@@ -17149,7 +17194,8 @@ async function runPostToolUse() {
       outcome: outcomeForClientFailure(clientResult.kind),
       failureReason: failure.reason,
       changeSet,
-      credential: evaluation.token
+      credential: evaluation.token,
+      credentialRefused: failure.kind === "credential"
     });
     if (failure.kind === "credential") {
       emitCredentialRejected(
@@ -17394,7 +17440,8 @@ async function runSessionDiff(input, kind) {
     emitLocalFault(`Could not get session diff: ${collected.message}`);
     return;
   }
-  const { files: changedFiles, getDiff } = collected;
+  const { getDiff } = collected;
+  const { evaluated: changedFiles } = partitionInstallerOutput(collected.files);
   if (changedFiles.length === 0) {
     return;
   }
@@ -17437,7 +17484,8 @@ async function runSessionDiff(input, kind) {
       failureReason: failure.reason,
       changeSet,
       diffBase,
-      credential: evaluation.token
+      credential: evaluation.token,
+      credentialRefused: failure.kind === "credential"
     });
     if (failure.kind === "credential") {
       emitCredentialRejected(

package/dist/bin.js

@@ -1761,10 +1761,45 @@ exit 0
 }
 function generateCiStanza() {
   return `# Halfcycle guard CI job \u2014 generated by the Halfcycle installer.
-# Paste this job into your CI workflow. It assumes no package manager and no
-# monorepo tooling: it runs the self-contained guard binary vendored at
-# .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.
+# Below is a complete GitHub Actions workflow: a name, the events it runs on, and
+# one job. It assumes no package manager and no monorepo tooling: it runs the
+# self-contained guard binary vendored at .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.
+#
+# NO WORKFLOW YET? Copy everything from the \`name:\` line to the end of the job
+# into a new file, .github/workflows/halfcycle-guard.yml, without the leading
+# "# " on each line. That file is complete as it stands: commit it, and the check
+# runs on the next push and on every pull request.
+#
+# ALREADY HAVE A WORKFLOW? Copy only the job \u2014 from \`halfcycle-guard-ci:\` down to
+# its \`run:\` line \u2014 under the \`jobs:\` key of the workflow you have, keeping the
+# indentation. The job carries its own \`permissions\` block, so it needs nothing
+# from the rest of that file.
+#
+# 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
@@ -1772,53 +1807,52 @@ function generateCiStanza() {
 # 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
-# check needs the commit BEFORE the one it is evaluating, and the default
+# Halfcycle engagements settle on. The \`on:\` block is what runs it in both
+# places: every push, and every pull request. Narrow it if you want (for example
+# \`branches: [main]\` under \`push:\`), but keep \`pull_request\`, or a change is
+# first checked after it has merged. \`fetch-depth\` is what makes the check work
+# there: it needs the commit BEFORE the one it is evaluating, and the default
 # shallow checkout does not have it. With \`fetch-depth: 0\` the check fails loudly
 # if it cannot work out what to evaluate \u2014 it will not pass quietly having
 # evaluated nothing.
 #
-# halfcycle-guard-ci:
-#   runs-on: ubuntu-latest
-#   steps:
-#     - uses: actions/checkout@v4
-#       with:
-#         # REQUIRED. 0 = full history. The check diffs against the commit before
-#         # HEAD (or the fork point on a branch); the default depth of 1 has
-#         # neither. Do not lower this.
-#         fetch-depth: 0
-#     - uses: actions/setup-node@v4
-#       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 }}
-#       run: node ./.halfcycle/bin/bin.bundle.mjs ci
+# name: Halfcycle guard
+# on:
+#   push:
+#   pull_request:
+# jobs:
+#   halfcycle-guard-ci:
+#     runs-on: ubuntu-latest
+#     permissions:
+#       contents: read
+#       id-token: write
+#     steps:
+#       - uses: actions/checkout@v4
+#         with:
+#           # REQUIRED. 0 = full history. The check diffs against the commit before
+#           # HEAD (or the fork point on a branch); the default depth of 1 has
+#           # neither. Do not lower this.
+#           fetch-depth: 0
+#       - uses: actions/setup-node@v4
+#         with:
+#           node-version: '20'
+#       - name: Halfcycle guard CI check
+#         # 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
-# also inert where it sits: no CI system reads this path. Copy the job above into
-# your own workflow and change it there.
+# also inert where it sits: no CI system reads this path. Copy the workflow above
+# \u2014 or just its job \u2014 into .github/workflows/ and change it there.
 `;
 }
 var MCP_REGISTRATION_REL = ".mcp.json";
@@ -1990,24 +2024,29 @@ ${header}
     return "failed";
   }
 }
-function previousAccountId(targetRepoRoot, engagementId) {
+function previousPinForEngagement(targetRepoRoot, engagementId) {
   try {
     const existing = readBundlePin(targetRepoRoot);
     if (existing === null || existing.engagementId !== engagementId)
       return void 0;
-    return existing.accountId;
+    return existing;
   } catch {
     return void 0;
   }
 }
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
 function writeBundlePin(targetRepoRoot, version, engagementId, engagementType, accountId, writtenPaths) {
-  const carried = accountId ?? previousAccountId(targetRepoRoot, engagementId);
+  const previous = previousPinForEngagement(targetRepoRoot, engagementId);
+  const carried = nonEmpty(accountId) ?? nonEmpty(previous?.accountId);
+  const installedAt = nonEmpty(previous?.installedAt) ?? (/* @__PURE__ */ new Date()).toISOString();
   const pin = {
     version,
     engagementId,
     engagementType,
-    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    ...carried !== void 0 && carried.trim() !== "" ? { accountId: carried } : {}
+    installedAt,
+    ...carried !== void 0 ? { accountId: carried } : {}
   };
   const pinPath = join5(targetRepoRoot, ".halfcycle", "bundle.json");
   writeAllowlisted(pinPath, targetRepoRoot, JSON.stringify(pin, null, 2) + "\n", writtenPaths);
@@ -4677,6 +4716,8 @@ ${USAGE}`);
         process.stdout.write(`[halfcycle] Next: open this folder in Claude Code \u2014 accept the workspace-trust prompt, it is expected \u2014 then run /halfcycle-setup and answer what it asks about your project
 `);
         process.stdout.write(`[halfcycle] Claude Code will also ask permission the first time Halfcycle needs to look up your next step. Choose allow \u2014 without it nothing can run.
+`);
+        process.stdout.write(`[halfcycle] To check changes in CI too: run \`npx halfcycle ci bind <owner>/<repo>\` in this folder once, then copy the workflow in .halfcycle/ci-stanza.yml into .github/workflows/ (or just its job into a workflow you have) \u2014 there is no secret to store.
 `);
       }
       if (credential) {