halfcycle 0.3.25 → 0.3.26

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.25",
+  "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

@@ -15142,14 +15142,25 @@ function emitNeverConfigured(missing, exitCode, reason) {
 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.`;
+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} GUARD NEVER CONFIGURED \u2014 this repository has no guard coverage.
+  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.
-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.
+${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.
 `;
@@ -15867,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: [] };
@@ -16433,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;
@@ -16722,7 +16749,9 @@ 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") });
 }
@@ -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,21 @@ 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
@@ -1798,31 +1809,39 @@ function generateCiStanza() {
 #
 # 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
-#   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
+# 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
@@ -1832,8 +1851,8 @@ function generateCiStanza() {
 #
 # 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";
@@ -2005,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);
@@ -4693,7 +4717,7 @@ ${USAGE}`);
 `);
         process.stdout.write(`[halfcycle] Claude Code will also ask permission the first time Halfcycle needs to look up your next step. Choose allow \u2014 without it nothing can run.
 `);
-        process.stdout.write(`[halfcycle] To check changes in CI too: run \`npx halfcycle ci bind <owner>/<repo>\` in this folder once, then paste the job from .halfcycle/ci-stanza.yml into a workflow \u2014 there is no secret to store.
+        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) {