halfcycle 0.3.7 → 0.3.8

package/.claude-plugin/plugin.json

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

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),
@@ -16018,6 +16042,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 +16141,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;
@@ -16189,16 +16262,19 @@ 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;
+    }
+    emitInfraWarning(failure.reason);
     return;
   }
   const telemetryConfig = readTelemetryConfig();
@@ -16442,17 +16518,20 @@ 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;
+    }
+    emitInfraWarning(failure.reason);
     return;
   }
   const telemetryConfig = readTelemetryConfig();

package/dist/bin.js

@@ -375,7 +375,31 @@ var firedGuardSchema = z2.object({
   guardId: z2.string(),
   patternRef: z2.string(),
   severity: severitySchema,
-  explanation: z2.string()
+  explanation: z2.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: z2.string().optional()
 }).strict();
 var resultEnvelopeSchema = z2.object({
   guardsFired: z2.array(firedGuardSchema),
@@ -489,6 +513,7 @@ var acceptanceOutcomeSchema = z4.object({
   findings: z4.number().int().nonnegative(),
   findingsDetail: z4.array(z4.object({ summary: z4.string() }).strict())
 }).strict();
+var PHASE_CLOSE_REASON_MAX = 1900;
 var phaseCloseDecisionSchema = z4.discriminatedUnion("decision", [
   z4.object({
     decision: z4.literal("done-when-met"),
@@ -499,8 +524,13 @@ var phaseCloseDecisionSchema = z4.discriminatedUnion("decision", [
     decision: z4.literal("override"),
     /** Who is closing it anyway. */
     actor: z4.string(),
-    /** Why, in their own words. */
-    reason: z4.string()
+    /**
+     * Why, in their own words. Bounded: the reason is kept on the phase's
+     * permanent record of its own close, and that record refuses anything
+     * longer — so an over-long reason is refused here, before the close is
+     * attempted, rather than failing the close itself.
+     */
+    reason: z4.string().max(PHASE_CLOSE_REASON_MAX)
   }).strict()
 ]);
 var acceptPhaseRequestSchema = z4.object({
@@ -586,7 +616,18 @@ var DEVICE_AUTH_STATUS = {
   /** Confirm: the shared confirmation secret was missing or wrong. 401. */
   UNAUTHORIZED: "unauthorized",
   /** Confirm: the code was already approved, declined or claimed. 409. */
-  ALREADY_DECIDED: "already-decided"
+  ALREADY_DECIDED: "already-decided",
+  /**
+   * Confirm: an approval named a signed-in identity whose account has not accepted
+   * the terms of service and privacy policy currently in force (T-18, #588). 400.
+   *
+   * NOT BOUND TO THE DEVICE CODE. Unlike every other refusal in this const, this one
+   * says nothing about the code itself — the code is still `pending` after this
+   * response, exactly as it was before the request, so the SAME userCode can be
+   * confirmed again once the caller has recorded acceptance. `deviceConfirmRequestSchema`'s
+   * `acceptTerms` is how a second confirm says it did.
+   */
+  TERMS_REQUIRED: "terms-required"
 };
 var DEVICE_POLL_REFUSALS = [
   DEVICE_AUTH_STATUS.DECLINED,
@@ -619,7 +660,8 @@ var deviceAuthRefusalSchema = z5.object({
     DEVICE_AUTH_STATUS.IDENTITY_REQUIRED,
     DEVICE_AUTH_STATUS.NOT_CONFIGURED,
     DEVICE_AUTH_STATUS.UNAUTHORIZED,
-    DEVICE_AUTH_STATUS.ALREADY_DECIDED
+    DEVICE_AUTH_STATUS.ALREADY_DECIDED,
+    DEVICE_AUTH_STATUS.TERMS_REQUIRED
   ]),
   message: z5.string().min(1)
 }).strict();
@@ -632,7 +674,8 @@ var deviceConfirmRequestSchema = z5.object({
   userCode: z5.string().min(1),
   decision: z5.enum(["approve", "decline"]),
   externalAuthId: z5.string().min(1).optional(),
-  email: z5.string().optional()
+  email: z5.string().optional(),
+  acceptTerms: z5.boolean().optional()
 }).strict();
 var deviceConfirmRecordedSchema = z5.object({
   status: z5.literal(DEVICE_AUTH_STATUS.RECORDED),
@@ -801,6 +844,18 @@ function writeCollisionSafe(targetAbsPath, targetRepoRoot, content) {
   writeFileSync4(targetAbsPath, content, "utf-8");
   return "written";
 }
+function writeOwned(targetAbsPath, targetRepoRoot, content) {
+  const rel = relative(targetRepoRoot, targetAbsPath).replace(/\\/g, "/");
+  if (!isAllowlisted(rel)) {
+    throw new Error(`[bundle install] Write-allowlist violation: attempted to write "${rel}". Only the method surface and scaffolding paths are writable.`);
+  }
+  if (existsSync3(targetAbsPath) && readFileSync5(targetAbsPath, "utf-8") === content) {
+    return "skipped";
+  }
+  mkdirSync4(dirname2(targetAbsPath), { recursive: true });
+  writeFileSync4(targetAbsPath, content, "utf-8");
+  return "written";
+}
 function record(report, outcome, rel) {
   const bucket = {
     written: report.writtenPaths,
@@ -921,6 +976,42 @@ if [ -z "$REPO_ROOT" ]; then exit 0; fi
 HASH="$(echo -n "$REPO_ROOT" | shasum -a 256 | cut -c1-12)"
 MARKER_FILE="\${TMPDIR%/}/halfcycle-session-\${HASH}.ref"
 git -C "$REPO_ROOT" rev-parse HEAD > "$MARKER_FILE" 2>/dev/null || true
+
+# ---------------------------------------------------------------------------
+# STANDING GUARD-COVERAGE STATEMENT (T-27).
+#
+# A repository with no credential on this machine is UNGUARDED: the PostToolUse
+# hook will find nothing to evaluate with, and it says so once per edit, after
+# the edit. This says it once, up front, before anything is written \u2014 which is
+# the one thing a session-start hook can do that nothing else can.
+#
+# Everything below runs in a SUBSHELL: it sources a credential store, and a
+# session-start hook must not leak an engagement's variables into whatever the
+# editor runs next. Any failure inside it is swallowed; this script's exit
+# status is 0 either way, and the marker above has already been written.
+# ---------------------------------------------------------------------------
+${engagementResolutionShell()}
+
+(
+  if halfcycle_env_file "$REPO_ROOT"; then
+    set -a
+    . "$HALFCYCLE_ENV_FILE"
+    set +a
+  fi
+  hc_missing=""
+  for hc_key in ${GUARD_ENV_KEYS.join(" ")}; do
+    eval "hc_value=\\\${$hc_key:-}"
+    if [ -z "$hc_value" ]; then hc_missing="$hc_missing $hc_key"; fi
+  done
+  if [ -n "$hc_missing" ]; then
+    echo "[halfcycle] NO GUARD COVERAGE IN THIS REPOSITORY. Nothing will evaluate the edits made in"
+    echo "[halfcycle] this session: this machine has no Halfcycle credential for it, so the guard hook"
+    echo "[halfcycle] has nothing to call with (missing:$hc_missing)."
+    echo "[halfcycle] Run \\"npx halfcycle\\" in this repository to fix it \u2014 it signs you in through your"
+    echo "[halfcycle] browser if needed, writes the credential to \\$HOME/.halfcycle outside this tree,"
+    echo "[halfcycle] and needs nothing configured first."
+  fi
+) 2>/dev/null || true
 exit 0
 `;
 }
@@ -934,6 +1025,13 @@ function generateUserPromptReminderHook() {
 # one home: RULE_SENTENCE_PLAIN in the method repo's own position-house-rule
 # test governs it \u2014 reword there and here together, in the same commit.
 #
+# SILENT WHEN THE TOOL IT NAMES IS NOT THERE. The sentence tells the session to
+# call halfcycle_resolve, which arrives over the Halfcycle MCP server registered
+# in .mcp.json. If this repository carries no such registration, the instruction
+# cannot be followed, and a per-prompt instruction that cannot be followed is
+# worse than silence. The standing "no coverage" statement belongs in the
+# session-start banner, which says it once; this hook just stops talking.
+#
 # FAILS OPEN. This hook's stdout is always plain text, never JSON, so it
 # cannot form a {"decision":"block",...} body (UserPromptSubmit's only way to
 # hold the turn). But a write failure here (a closed stdout, say) must still
@@ -941,6 +1039,26 @@ function generateUserPromptReminderHook() {
 # than propagate.
 trap 'exit 0' ERR
 set -e
+
+# The project root is resolved from THIS SCRIPT'S OWN LOCATION, never from the
+# session's cwd \u2014 a session started in a subdirectory must find the same root
+# .mcp.json the editor loaded, which is the bug mcp-headers.sh already paid for.
+HC_SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+HC_PROJECT_ROOT=$(CDPATH= cd -- "$HC_SCRIPT_DIR/../.." && pwd)
+HC_REGISTRATION="$HC_PROJECT_ROOT/${MCP_REGISTRATION_REL}"
+
+# Presence of the FILE is not enough \u2014 a developer's own .mcp.json with no
+# Halfcycle server in it registers no halfcycle_resolve. \`grep\` is guarded with
+# \`|| true\` because a non-match is a status, not an error, and \`set -e\` would
+# otherwise route it through the trap (same outcome here, but by accident).
+HC_REGISTERED=""
+if [ -f "$HC_REGISTRATION" ]; then
+  HC_REGISTERED=$(tr -d '\\n' < "$HC_REGISTRATION" | grep -c '"${MCP_SERVER_KEY}"[[:space:]]*:' || true)
+fi
+if [ -z "$HC_REGISTERED" ] || [ "$HC_REGISTERED" = "0" ]; then
+  exit 0
+fi
+
 printf '%s\\n' '${USER_PROMPT_REMINDER_SENTENCE}'
 exit 0
 `;
@@ -1022,8 +1140,13 @@ GUARD_ENGAGEMENT_ID=<argType:runtime>
 # TWO ORIGINS, TWO SERVICES (T-22). HALFCYCLE_SERVICE_URL is the Halfcycle
 # CONTROL plane \u2014 it serves engagement creation and the board's first-visit
 # code. HALFCYCLE_MCP_URL is the method-delivery service, which serves /mcp and
-# nothing else here. You configure the first; the platform reports the second on
-# create, so it is written for you and .mcp.json carries the composed address.
+# nothing else here. The platform reports the second on create, so it is written
+# for you and .mcp.json carries the composed address.
+#
+# NEITHER IS SOMETHING YOU NEED TO SET (T-27). The installer talks to Halfcycle's
+# own control plane by default; HALFCYCLE_SERVICE_URL OVERRIDES that address and
+# exists for a self-hosted or development plane. It is not a prerequisite for
+# \`npx halfcycle\`, and nothing in the product asks you to find its value.
 HALFCYCLE_SERVICE_URL=<argType:runtime>
 HALFCYCLE_MCP_URL=<argType:runtime>
 HALFCYCLE_TOKEN=<argType:runtime>
@@ -1036,6 +1159,7 @@ CONTROL_TELEMETRY_URL=<argType:runtime>
 `;
 }
 var MCP_REGISTRATION_REL = ".mcp.json";
+var MCP_SERVER_KEY = "halfcycle";
 var MCP_HEADERS_HELPER_REL = ".halfcycle/mcp-headers.sh";
 var MCP_HEADERS_HELPER_COMMAND = `/bin/sh -c 'd=$(pwd); while [ ! -f "$d/${MCP_HEADERS_HELPER_REL}" ] && [ "$d" != / ]; do d=$(dirname "$d"); done; [ -f "$d/${MCP_HEADERS_HELPER_REL}" ] || { echo "halfcycle: ${MCP_HEADERS_HELPER_REL} not found at or above $(pwd); re-run npx halfcycle" >&2; exit 1; }; exec /bin/sh "$d/${MCP_HEADERS_HELPER_REL}"'`;
 function generateMcpHeadersHelper() {
@@ -1148,7 +1272,7 @@ function generateMcpRegistration(existing, mcpOrigin) {
   if (typeof base.mcpServers !== "object" || base.mcpServers === null) {
     base.mcpServers = {};
   }
-  base.mcpServers["halfcycle"] = {
+  base.mcpServers[MCP_SERVER_KEY] = {
     type: "http",
     url: mcpEndpointUrl(mcpOrigin),
     headersHelper: MCP_HEADERS_HELPER_COMMAND
@@ -1370,7 +1494,7 @@ async function install(options) {
   }
   const vendoredBinSrc = resolveVendoredBinary();
   const vendoredBinDest = join5(targetRepo, ".halfcycle", "bin", "bin.bundle.mjs");
-  record(report, writeCollisionSafe(vendoredBinDest, targetRepo, readFileSync5(vendoredBinSrc, "utf-8")), ".halfcycle/bin/bin.bundle.mjs");
+  record(report, writeOwned(vendoredBinDest, targetRepo, readFileSync5(vendoredBinSrc, "utf-8")), ".halfcycle/bin/bin.bundle.mjs");
   const settingsPath = join5(targetRepo, ".claude", "settings.json");
   const settingsPreexisted = existsSync3(settingsPath);
   const generatedSettings = JSON.parse(generateSettingsJson());
@@ -1451,6 +1575,18 @@ async function install(options) {
   };
 }
 
+// dist/control-origin.js
+var DEFAULT_CONTROL_ORIGIN = "https://control.halfcycle.ai";
+function resolveControlOrigin(env = process.env) {
+  const configured = env["HALFCYCLE_SERVICE_URL"]?.trim();
+  if (configured)
+    return { origin: configured.replace(/\/+$/, ""), source: "environment" };
+  return { origin: DEFAULT_CONTROL_ORIGIN, source: "default" };
+}
+function controlOriginNote(resolved) {
+  return resolved.source === "environment" ? `${resolved.origin} (from HALFCYCLE_SERVICE_URL)` : `${resolved.origin} (the Halfcycle plane; set HALFCYCLE_SERVICE_URL to use another)`;
+}
+
 // dist/create-engagement.js
 var CreateEngagementRefused = class extends Error {
   status;
@@ -1508,7 +1644,7 @@ function planeRefusal(detail) {
     error: typeof candidate.error === "string" ? candidate.error : void 0
   };
 }
-var CONTROL_ORIGIN_HINT = "HALFCYCLE_SERVICE_URL must be the Halfcycle CONTROL origin \u2014 the one that serves /engagements and /board/enter-codes. The MCP server runs at a different address, and the platform supplies that one itself; you do not configure it.";
+var CONTROL_ORIGIN_HINT = `With nothing configured this CLI talks to ${DEFAULT_CONTROL_ORIGIN}; HALFCYCLE_SERVICE_URL overrides that, and is only for a self-hosted or development plane. Whichever is in use, it must be the CONTROL origin \u2014 the one that serves /engagements and /board/enter-codes. The MCP server runs at a different address, and the platform supplies that one itself; you do not configure it.`;
 async function createEngagement(baseUrl, name, credential) {
   return requestEngagementValues(`${baseUrl.replace(/\/+$/, "")}/engagements`, name ? { name } : {}, credential, { action: "Create-engagement", nothingHappened: "No engagement was created", route: "POST /engagements" });
 }
@@ -2500,7 +2636,7 @@ async function closePhase(credential, phase, outcome, close) {
   }
   const parsedClose = phaseCloseDecisionSchema.safeParse(close);
   if (!parsedClose.success) {
-    throw new Error(`[halfcycle] That is not a phase-close decision this platform accepts: ${parsedClose.error.issues.map((i) => i.message).join("; ")}.`);
+    throw new Error(`[halfcycle] That is not a phase-close decision this platform accepts: ${parsedClose.error.issues.map((i) => `${i.path.join(".") || "(decision)"}: ${i.message}`).join("; ")}.`);
   }
   const url = `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/accept`;
   let res;
@@ -2774,45 +2910,43 @@ ${USAGE}`);
       return;
     }
     try {
-      const serviceUrl = process.env.HALFCYCLE_SERVICE_URL?.trim();
-      const pinned = engagementIdArg === void 0 ? readPinnedEngagement(targetRepo) : null;
-      let engagementId = engagementIdArg ?? pinned?.engagementId ?? "engagement-001";
+      const controlOrigin = resolveControlOrigin(process.env);
+      const serviceUrl = controlOrigin.origin;
+      process.stdout.write(`[halfcycle] Halfcycle plane: ${controlOriginNote(controlOrigin)}
+`);
+      const pinned = readPinnedEngagement(targetRepo);
+      const requestedId = engagementIdArg ?? pinned?.engagementId;
+      const reusable = pinned !== null && pinned.engagementId === requestedId ? pinned.credential : void 0;
+      let engagementId;
       let credential;
-      if (pinned) {
-        credential = pinned.credential;
+      if (reusable !== void 0 && pinned !== null) {
+        engagementId = pinned.engagementId;
+        credential = reusable;
         process.stdout.write(`[halfcycle] Re-using the engagement already pinned in this repo: ${pinned.engagementId}
 `);
-        if (credential === void 0 && serviceUrl) {
-          const joined = await joinPinnedEngagement(serviceUrl, pinned.engagementId);
-          credential = {
-            serviceUrl,
-            token: joined.sessionToken,
-            mcpUrl: joined.mcpUrl,
-            guardUrl: joined.guardUrl,
-            // T-10 — optional; absent on a plane that has not configured
-            // CONTROL_TELEMETRY_URL yet. `writeEngagementCredential` writes '' for
-            // an absent value, never `undefined` verbatim.
-            controlTelemetryUrl: joined.controlTelemetryUrl
-          };
-          process.stdout.write(`[halfcycle] Joined engagement ${joined.engagementId} \u2014 this credential is yours. Everyone else's keeps working; nobody was signed out and nothing was pasted.
-`);
-        } else if (credential === void 0) {
-          process.stdout.write(`[halfcycle] This machine holds no credential for it, and HALFCYCLE_SERVICE_URL is not
-[halfcycle] set \u2014 so there is no plane to ask for one. Nothing will be minted, and the
-[halfcycle] board link and MCP calls will not work until it is. Looked in
-[halfcycle] ${engagementEnvPath(pinned.engagementId)}.
-[halfcycle] Set that variable and re-run to get a credential of your own for this
-[halfcycle] engagement. To start a NEW engagement instead, remove
-[halfcycle] .halfcycle/bundle.json first.
-`);
-        } else if (pinned.fromLegacyEnvLocal) {
+        if (pinned.fromLegacyEnvLocal) {
           process.stdout.write(`[halfcycle] Its credential is in this repository's .env.local \u2014 an install from before
 [halfcycle] credentials moved out of the tree. It is being copied to
 [halfcycle] ${engagementEnvPath(pinned.engagementId)} and taken back out of .env.local.
 [halfcycle] Anything else that file holds is untouched.
 `);
         }
-      } else if (serviceUrl && engagementIdArg === void 0) {
+      } else if (requestedId !== void 0) {
+        const joined = await joinPinnedEngagement(serviceUrl, requestedId);
+        engagementId = joined.engagementId;
+        credential = {
+          serviceUrl,
+          token: joined.sessionToken,
+          mcpUrl: joined.mcpUrl,
+          guardUrl: joined.guardUrl,
+          // T-10 — optional; absent on a plane that has not configured
+          // CONTROL_TELEMETRY_URL yet. `writeEngagementCredential` writes '' for
+          // an absent value, never `undefined` verbatim.
+          controlTelemetryUrl: joined.controlTelemetryUrl
+        };
+        process.stdout.write(`[halfcycle] Joined engagement ${joined.engagementId} \u2014 this credential is yours. Everyone else's keeps working; nobody was signed out and nothing was pasted.
+`);
+      } else {
         const created = await createOwnedEngagement(serviceUrl);
         engagementId = created.engagementId;
         credential = {
@@ -2863,44 +2997,32 @@ ${USAGE}`);
 [halfcycle] ${missing.length === 1 ? "it" : "them"}) and re-run, and the credential moves out of the tree.
 `);
       }
-      if (credential) {
-        const probe = await probeMcpOrigin(credential.mcpUrl);
-        if (probe.reached) {
-          process.stdout.write(`[halfcycle] Method delivery (MCP): ${credential.mcpUrl} \u2014 reachable (${probe.serverName})
-`);
-        } else {
-          process.stdout.write(`[halfcycle] Method delivery (MCP): ${credential.mcpUrl} \u2014 NOT reachable: ${probe.problem}.
-[halfcycle] The Halfcycle commands will have no method context until that address answers. This is the SECOND of two origins and the platform supplied it, so it is not your HALFCYCLE_SERVICE_URL (${credential.serviceUrl}) that is wrong \u2014 that one just worked. It is recorded as HALFCYCLE_MCP_URL in this engagement's credential store; re-run this installer once the service is up.
-`);
-        }
-      }
-      if (credential) {
-        process.stdout.write(`[halfcycle] Guard evaluation: ON \u2014 the hook evaluates against ${credential.guardUrl}. Credentials (${GUARD_ENV_KEYS.join(", ")}) are in ${engagementEnvPath(engagementId)}, outside this repository; the hook loads them itself, so you do not export anything and nothing here can be committed.
+      const probe = await probeMcpOrigin(credential.mcpUrl);
+      if (probe.reached) {
+        process.stdout.write(`[halfcycle] Method delivery (MCP): ${credential.mcpUrl} \u2014 reachable (${probe.serverName})
 `);
       } else {
-        const remedy = pinned ? `Set HALFCYCLE_SERVICE_URL to the Halfcycle CONTROL origin and re-run \u2014 this repo is pinned to engagement ${pinned.engagementId}, and with a plane to ask, the installer mints you a credential of your own for it, at ${engagementEnvPath(pinned.engagementId)}. To start a NEW engagement here instead, remove .halfcycle/bundle.json and re-run.` : engagementIdArg !== void 0 ? `This install named engagement ${engagementIdArg} explicitly, which skips the create that mints a credential. This repo is now pinned to it, so re-run \`npx halfcycle\` with no id and the installer will mint you a credential of your own for it. To start a NEW engagement instead, remove .halfcycle/bundle.json and re-run.` : `Set HALFCYCLE_SERVICE_URL to the Halfcycle CONTROL origin and re-run this installer.`;
-        process.stdout.write(`[halfcycle] Guard evaluation: OFF \u2014 this install had no credential, so no guard will run in this repository and edits are unguarded. ${remedy}
+        process.stdout.write(`[halfcycle] Method delivery (MCP): ${credential.mcpUrl} \u2014 NOT reachable: ${probe.problem}.
+[halfcycle] The Halfcycle commands will have no method context until that address answers. This is the SECOND of two origins and the platform supplied it, so it is not the CONTROL origin (${credential.serviceUrl}) that is wrong \u2014 that one just worked. It is recorded as HALFCYCLE_MCP_URL in this engagement's credential store; re-run this installer once the service is up.
 `);
       }
-      if (credential) {
-        process.stdout.write(`[halfcycle] Your credential is at ${engagementEnvPath(engagementId)} \u2014 outside this repository, readable only by you. .mcp.json reads it at connection time through .halfcycle/mcp-headers.sh, so there is no token in this tree to commit and nothing for you to export.
+      process.stdout.write(`[halfcycle] Guard evaluation: ON \u2014 the hook evaluates against ${credential.guardUrl}. Credentials (${GUARD_ENV_KEYS.join(", ")}) are in ${engagementEnvPath(engagementId)}, outside this repository; the hook loads them itself, so you do not export anything and nothing here can be committed.
 `);
-        process.stdout.write(`[halfcycle] Expect a workspace trust prompt the first time you open this folder \u2014 the helper is a shell command, and Claude Code will not run it until you accept. Needs Claude Code ${MIN_HEADERS_HELPER_VERSION} or newer (${MIN_HEADER_ROTATION_VERSION}+ to re-authenticate a rotated token without restarting).
+      process.stdout.write(`[halfcycle] Your credential is at ${engagementEnvPath(engagementId)} \u2014 outside this repository, readable only by you. .mcp.json reads it at connection time through .halfcycle/mcp-headers.sh, so there is no token in this tree to commit and nothing for you to export.
 `);
-        process.stdout.write(`[halfcycle] If Halfcycle tools appear but every call returns 401, the helper could not read HALFCYCLE_TOKEN from ${engagementEnvPath(engagementId)} \u2014 re-run this installer.
+      process.stdout.write(`[halfcycle] Expect a workspace trust prompt the first time you open this folder \u2014 the helper is a shell command, and Claude Code will not run it until you accept. Needs Claude Code ${MIN_HEADERS_HELPER_VERSION} or newer (${MIN_HEADER_ROTATION_VERSION}+ to re-authenticate a rotated token without restarting).
 `);
-        reportClaudeCodeVersion();
-      }
-      if (credential) {
-        try {
-          const minted = await mintBoardEnterCode(credential.serviceUrl, credential.token);
-          process.stdout.write(`[halfcycle] Your board (first visit): ${minted.boardUrl}
+      process.stdout.write(`[halfcycle] If Halfcycle tools appear but every call returns 401, the helper could not read HALFCYCLE_TOKEN from ${engagementEnvPath(engagementId)} \u2014 re-run this installer.
 `);
-          process.stdout.write(`[halfcycle] First-visit code \u2014 single use, expires ${minted.expiresAt}; paste it on that page, and re-run this installer for a fresh one: ${minted.enterCode}
+      reportClaudeCodeVersion();
+      try {
+        const minted = await mintBoardEnterCode(credential.serviceUrl, credential.token);
+        process.stdout.write(`[halfcycle] Your board (first visit): ${minted.boardUrl}
 `);
-        } catch {
-          process.stdout.write("[halfcycle] Your board: no first-visit code was issued just now \u2014 re-run this installer to get one.\n");
-        }
+        process.stdout.write(`[halfcycle] First-visit code \u2014 single use, expires ${minted.expiresAt}; paste it on that page, and re-run this installer for a fresh one: ${minted.enterCode}
+`);
+      } catch {
+        process.stdout.write("[halfcycle] Your board: no first-visit code was issued just now \u2014 re-run this installer to get one.\n");
       }
       process.exit(0);
     } catch (err) {