halfcycle 0.3.7 → 0.3.9

package/.claude-plugin/plugin.json

@@ -1,16 +1,43 @@
 {
   "name": "halfcycle",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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": [
-    { "name": "halfcycle-setup", "path": "../commands/halfcycle-setup.md" },
-    { "name": "halfcycle-design", "path": "../commands/halfcycle-design.md" },
-    { "name": "write-spec", "path": "../commands/write-spec.md" },
-    { "name": "consistency-check", "path": "../commands/consistency-check.md" },
-    { "name": "task-graph", "path": "../commands/task-graph.md" },
-    { "name": "context-update", "path": "../commands/context-update.md" },
-    { "name": "agent-teams-orchestration", "path": "../commands/agent-teams-orchestration.md" },
-    { "name": "task-execution", "path": "../commands/task-execution.md" },
-    { "name": "stack-assembly-worker", "path": "../commands/stack-assembly-worker.md" }
+    {
+      "name": "halfcycle-setup",
+      "path": "../commands/halfcycle-setup.md"
+    },
+    {
+      "name": "halfcycle-design",
+      "path": "../commands/halfcycle-design.md"
+    },
+    {
+      "name": "write-spec",
+      "path": "../commands/write-spec.md"
+    },
+    {
+      "name": "consistency-check",
+      "path": "../commands/consistency-check.md"
+    },
+    {
+      "name": "task-graph",
+      "path": "../commands/task-graph.md"
+    },
+    {
+      "name": "context-update",
+      "path": "../commands/context-update.md"
+    },
+    {
+      "name": "agent-teams-orchestration",
+      "path": "../commands/agent-teams-orchestration.md"
+    },
+    {
+      "name": "task-execution",
+      "path": "../commands/task-execution.md"
+    },
+    {
+      "name": "stack-assembly-worker",
+      "path": "../commands/stack-assembly-worker.md"
+    }
   ]
 }

package/README.md

@@ -8,6 +8,8 @@ npx halfcycle
 
 That is the whole install. One command, in the repo you want to work in.
 
+**Where it connects.** That command talks to Halfcycle at `https://control.halfcycle.ai`, to sign you in through your browser and to create the engagement your work is recorded against. It is the same address for everybody and it ships in the CLI, so there is nothing to configure, nothing to look up, and no value anyone has to give you first; the addresses for your board and for the checks come back from there too. If it cannot be reached, the install stops and writes nothing rather than setting your repository up without cover.
+
 ---
 
 ## What it is

package/bin/bin.bundle.mjs

@@ -14608,7 +14608,31 @@ var firedGuardSchema = external_exports.object({
   guardId: external_exports.string(),
   patternRef: external_exports.string(),
   severity: severitySchema,
-  explanation: external_exports.string()
+  explanation: external_exports.string(),
+  /**
+   * The repo-relative path of the file this firing was decided on. The matcher
+   * has the file live at the moment it decides to fire; this is the field that
+   * carries the answer out. It is the CLIENT's own coordinate — the wire type
+   * still has no field for a matcher body, a channel, a version, a scope or a
+   * guard's provenance, and physically cannot carry one.
+   *
+   * THE PRESENCE RULE, WHICH LIVES HERE AND NOT IN A CONSUMER'S PROSE: every
+   * firing produced from this contract version onward carries `path`, so on the
+   * WIRE, absence means exactly one thing — a response from a guard service
+   * older than this contract. It is declared optional because a client's guard
+   * runner is built from its own checkout and calls a service that may be older
+   * than it; a required field would make that pairing unparseable.
+   *
+   * The rule does NOT transfer to a store that persists a firing, where an
+   * absent path has a second legitimate meaning: a row written before the
+   * column existed. A persisted NULL is therefore not a writer bug.
+   *
+   * NO SHAPE CONSTRAINT. This value is whatever the changed tree called the
+   * file. A consumer that maps it onto a coordinate with its own path rule must
+   * safe-parse it and decide what to do with a refusal, rather than assume the
+   * two shapes agree.
+   */
+  path: external_exports.string().optional()
 }).strict();
 var resultEnvelopeSchema = external_exports.object({
   guardsFired: external_exports.array(firedGuardSchema),
@@ -16003,6 +16027,15 @@ 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) {
@@ -16018,6 +16051,52 @@ This is not a service outage. It means the guard has never run here \u2014 not o
 ${remedy}
 `;
 }
+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;
+}
 
 // dist/ci.js
 async function runCi() {
@@ -16071,21 +16150,24 @@ async function runCi() {
     changeSet
   });
   if (!clientResult.ok) {
-    const isInfra = clientResult.kind === "infra-error" || clientResult.kind === "wire-error";
-    const failureReason = isInfra ? `infrastructure failure: ${clientResult.message}` : `contract error: ${clientResult.message}`;
+    const failure = classifyFailure(clientResult);
     await emitRunRecord({
       engagementId: guardEngagementId,
       runType: "ci",
       outcome: outcomeForClientFailure(clientResult.kind),
-      failureReason,
+      failureReason: failure.reason,
       changeSet
     });
-    if (isInfra) {
-      process.stderr.write(`[Halfcycle CI] Infrastructure failure: Guard service unavailable \u2014 ${clientResult.message}
+    if (failure.kind === "credential") {
+      process.stderr.write(credentialRejectedMessage(failure.statusCode, failure.message, CI_REMEDY, "[Halfcycle CI]"));
+      return 1;
+    }
+    if (failure.kind === "service") {
+      process.stderr.write(`[Halfcycle CI] Infrastructure failure: Guard service unavailable \u2014 ${failure.message}
   This is NOT a guard violation. Fix the infrastructure issue and re-run.
 `);
     } else {
-      process.stderr.write(`[Halfcycle CI] Infrastructure failure (contract error): ${clientResult.message}
+      process.stderr.write(`[Halfcycle CI] Infrastructure failure (contract error): ${failure.message}
 `);
     }
     return 1;
@@ -16165,7 +16247,7 @@ async function runPostToolUse() {
     return;
   const repoRootResult = getRepoRoot(process.cwd());
   if (!repoRootResult.ok) {
-    emitInfraWarning(`Could not find git repo root: ${repoRootResult.message}`);
+    emitLocalFault(`Could not find git repo root: ${repoRootResult.message}`);
     return;
   }
   const repoRoot = repoRootResult.value;
@@ -16189,16 +16271,23 @@ async function runPostToolUse() {
     changeSet
   });
   if (!clientResult.ok) {
-    const isInfra = clientResult.kind === "infra-error" || clientResult.kind === "wire-error";
-    const errorLabel = isInfra ? "infrastructure failure" : "contract error";
+    const failure = classifyFailure(clientResult);
     await emitRunRecord({
       engagementId: guardEngagementId,
       runType: "hook",
       outcome: outcomeForClientFailure(clientResult.kind),
-      failureReason: `${errorLabel}: ${clientResult.message}`,
+      failureReason: failure.reason,
       changeSet
     });
-    emitInfraWarning(`${errorLabel}: ${clientResult.message}`);
+    if (failure.kind === "credential") {
+      emitCredentialRejected(failure.statusCode, failure.message, CREDENTIAL_REJECTED_EXIT_TOOL_USE);
+      return;
+    }
+    if (failure.kind === "contract") {
+      emitContractFault(failure.message);
+      return;
+    }
+    emitInfraWarning(failure.reason);
     return;
   }
   const telemetryConfig = readTelemetryConfig();
@@ -16401,7 +16490,7 @@ function collectDiff(repoRoot, base) {
 async function runSessionDiff(input, kind) {
   const repoRootResult = getRepoRoot(process.cwd());
   if (!repoRootResult.ok) {
-    emitInfraWarning(`Could not find git repo root: ${repoRootResult.message}`);
+    emitLocalFault(`Could not find git repo root: ${repoRootResult.message}`);
     return;
   }
   const repoRoot = repoRootResult.value;
@@ -16411,7 +16500,7 @@ async function runSessionDiff(input, kind) {
   const diffBase = base.kind;
   const collected = collectDiff(repoRoot, base);
   if (!collected.ok) {
-    emitInfraWarning(`Could not get session diff: ${collected.message}`);
+    emitLocalFault(`Could not get session diff: ${collected.message}`);
     return;
   }
   const { files: changedFiles, getDiff } = collected;
@@ -16442,17 +16531,24 @@ async function runSessionDiff(input, kind) {
     changeSet
   });
   if (!clientResult.ok) {
-    const isInfra = clientResult.kind === "infra-error" || clientResult.kind === "wire-error";
-    const errorLabel = isInfra ? "infrastructure failure" : "contract error";
+    const failure = classifyFailure(clientResult);
     await emitRunRecord({
       engagementId: guardEngagementId,
       runType: "hook",
       outcome: outcomeForClientFailure(clientResult.kind),
-      failureReason: `${errorLabel}: ${clientResult.message}`,
+      failureReason: failure.reason,
       changeSet,
       diffBase
     });
-    emitInfraWarning(`${errorLabel}: ${clientResult.message}`);
+    if (failure.kind === "credential") {
+      emitCredentialRejected(failure.statusCode, failure.message, CREDENTIAL_REJECTED_EXIT_STOP_FAMILY);
+      return;
+    }
+    if (failure.kind === "contract") {
+      emitContractFault(failure.message);
+      return;
+    }
+    emitInfraWarning(failure.reason);
     return;
   }
   const telemetryConfig = readTelemetryConfig();