halfcycle 0.4.0 → 0.4.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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/README.md

@@ -167,11 +167,7 @@ Nothing you already had is changed. Existing settings are preserved, and a name
 - Claude Code **2.1.118+**
 - Node 20+
 - A git repository
-- On Windows, if you use PowerShell: let it run the scripts Node installs, once per user. Otherwise PowerShell refuses `npx` with *running scripts is disabled on this system*:
-
-  ```powershell
-  Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
-  ```
+- On Windows, in PowerShell, use `npx.cmd` instead of `npx` (PowerShell's default settings block the `npx` script; `npx.cmd` always works, with nothing to change).
 
 ## Getting started
 
@@ -181,19 +177,19 @@ git init
 npx halfcycle
 ```
 
-In Windows PowerShell, separate the first two commands with `;` instead of `&&`:
+In Windows PowerShell, separate the first two commands with `;` instead of `&&`, and run `npx.cmd` instead of `npx`:
 
 ```powershell
 mkdir my-project; cd my-project
 git init
-npx halfcycle
+npx.cmd halfcycle
 ```
 
 Then open the folder in Claude Code and run `/halfcycle-setup`, and answer the questions it asks about your project.
 
 **Accept the workspace trust prompt when Claude Code shows it.** The install writes a credential helper and a set of hooks that are shell commands, so Claude Code asks before it runs them. It is expected.
 
-**A second prompt follows — it is not the trust prompt again.** After you accept the trust prompt, Claude Code asks whether to use a new MCP server. The cursor starts on *Continue without using this MCP server*; choose to use the server instead, or Halfcycle will not connect.
+**A second prompt follows — it is not the trust prompt again.** After you accept the trust prompt, Claude Code asks whether to use a new MCP server. If halfcycle is the only one listed, the cursor starts on *Continue without using this MCP server*; choose to use the server instead, or Halfcycle will not connect. If several new servers are listed together, halfcycle is already checked — leave it that way.
 
 You will get a board link on install. That is where the work becomes visible to anyone who is not you.
 

package/bin/bin.bundle.mjs

@@ -14664,58 +14664,70 @@ var GUARD_RUNNER_REL = ".claude/hooks/guard-runner.sh";
 var USER_PROMPT_REMINDER_REL = ".claude/hooks/user-prompt-reminder.sh";
 var SESSION_END_MARKER_REL = ".claude/hooks/session-end-marker.sh";
 var WRITE_CAPABLE_TOOLS = ["Edit", "MultiEdit", "NotebookEdit", "Write"];
+function hookCommand(script, verb) {
+  const invocation = `bash "$CLAUDE_PROJECT_DIR"/${script}`;
+  return verb === void 0 ? invocation : `${invocation} ${verb}`;
+}
 var HALFCYCLE_HOOK_WIRING = [
   {
     event: "SessionStart",
     matcher: null,
     timeout: 5,
-    command: `bash ./${SESSION_START_MARKER_REL}`,
+    command: hookCommand(SESSION_START_MARKER_REL),
     script: SESSION_START_MARKER_REL
   },
   {
     event: "SessionStart",
     matcher: null,
     timeout: 10,
-    command: `bash ./${GUARD_RUNNER_REL} refresh-credential`,
+    command: hookCommand(GUARD_RUNNER_REL, "refresh-credential"),
     script: GUARD_RUNNER_REL
   },
   {
     event: "UserPromptSubmit",
     matcher: null,
     timeout: 5,
-    command: `bash ./${USER_PROMPT_REMINDER_REL}`,
+    command: hookCommand(USER_PROMPT_REMINDER_REL),
     script: USER_PROMPT_REMINDER_REL
   },
   {
     event: "PostToolUse",
     matcher: WRITE_CAPABLE_TOOLS.join("|"),
     timeout: 60,
-    command: `bash ./${GUARD_RUNNER_REL} hook post-tool-use`,
+    command: hookCommand(GUARD_RUNNER_REL, "hook post-tool-use"),
     script: GUARD_RUNNER_REL
   },
   {
     event: "Stop",
     matcher: null,
     timeout: 60,
-    command: `bash ./${GUARD_RUNNER_REL} hook stop`,
+    command: hookCommand(GUARD_RUNNER_REL, "hook stop"),
     script: GUARD_RUNNER_REL
   },
   {
     event: "SubagentStop",
     matcher: null,
     timeout: 60,
-    command: `bash ./${GUARD_RUNNER_REL} hook subagent-stop`,
+    command: hookCommand(GUARD_RUNNER_REL, "hook subagent-stop"),
     script: GUARD_RUNNER_REL
   },
   {
     event: "SessionEnd",
     matcher: null,
     timeout: 5,
-    command: `bash ./${SESSION_END_MARKER_REL}`,
+    command: hookCommand(SESSION_END_MARKER_REL),
     script: SESSION_END_MARKER_REL
   }
 ];
-var RETIRED_HOOK_COMMANDS = [];
+var RETIRED_HOOK_COMMANDS = [
+  "bash ./.claude/hooks/session-start-marker.sh",
+  "bash ./.claude/hooks/guard-runner.sh refresh-credential",
+  "bash ./.claude/hooks/user-prompt-reminder.sh",
+  "bash ./.claude/hooks/guard-runner.sh hook post-tool-use",
+  "bash ./.claude/hooks/guard-runner.sh hook stop",
+  "bash ./.claude/hooks/guard-runner.sh hook subagent-stop",
+  "bash ./.claude/hooks/session-end-marker.sh"
+];
 var HALFCYCLE_HOOK_COMMANDS = /* @__PURE__ */ new Set([
   ...HALFCYCLE_HOOK_WIRING.map((entry) => entry.command),
   ...RETIRED_HOOK_COMMANDS
@@ -15738,15 +15750,18 @@ function getSingleFileDiff(absFilePath, repoRoot) {
     return "";
   }
 }
+function workingTreeBase(repoRoot) {
+  return refExists("HEAD", repoRoot) ? "HEAD" : EMPTY_TREE_SHA;
+}
 function getWorkingTreeChangedFiles(repoRoot) {
-  const result = git(["diff", "HEAD", "--name-only", "--diff-filter=d"], repoRoot);
+  const result = git(["diff", workingTreeBase(repoRoot), "--name-only", "--diff-filter=d"], repoRoot);
   if (!result.ok)
     return result;
   const files = result.value.split("\n").map((l) => l.trim()).filter(Boolean);
   return { ok: true, value: files };
 }
 function getWorkingTreeFileDiff(relPath, repoRoot) {
-  const result = git(["diff", "HEAD", "--", relPath], repoRoot);
+  const result = git(["diff", workingTreeBase(repoRoot), "--", relPath], repoRoot);
   if (result.ok && result.value.trim())
     return result.value;
   return "";
@@ -17450,10 +17465,143 @@ async function evaluateWithRefresh(opts) {
   return { result: retry, token: refreshed.token, remedy: HOOK_REMEDY };
 }
 
+// dist/hooks/marker.js
+import { createHash } from "node:crypto";
+import { existsSync as existsSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync3, unlinkSync as unlinkSync3, readdirSync as readdirSync3, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join as join6 } from "node:path";
+var MARKER_TTL_MS = 24 * 60 * 60 * 1e3;
+var MARKER_PREFIX = "halfcycle-session-";
+var MARKER_SUFFIX = ".ref";
+var DEDUPE_SUFFIX = ".eval";
+function markerDir() {
+  const raw = process.env["TMPDIR"] ?? tmpdir();
+  return raw.replace(/\/+$/, "");
+}
+function repoHash(repoRoot) {
+  return createHash("sha256").update(repoRoot).digest("hex").slice(0, 12);
+}
+function markerFileName(repoRoot, sessionId) {
+  const hash2 = repoHash(repoRoot);
+  const key = sessionId && sessionId.length > 0 ? `${hash2}-${sessionId}` : hash2;
+  return `${MARKER_PREFIX}${key}${MARKER_SUFFIX}`;
+}
+function markerPath(repoRoot, sessionId) {
+  return join6(markerDir(), markerFileName(repoRoot, sessionId));
+}
+function dedupePath(repoRoot, sessionId) {
+  const hash2 = repoHash(repoRoot);
+  const key = sessionId && sessionId.length > 0 ? `${hash2}-${sessionId}` : hash2;
+  return join6(markerDir(), `${MARKER_PREFIX}${key}${DEDUPE_SUFFIX}`);
+}
+function readMarker(repoRoot, sessionId) {
+  const path = markerPath(repoRoot, sessionId);
+  if (!existsSync3(path))
+    return null;
+  try {
+    return readFileSync6(path, "utf-8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+function deleteMarker(repoRoot, sessionId) {
+  for (const path of [markerPath(repoRoot, sessionId), dedupePath(repoRoot, sessionId)]) {
+    try {
+      if (existsSync3(path))
+        unlinkSync3(path);
+    } catch {
+    }
+  }
+}
+var NO_REPO_NOTICE_SUFFIX = ".norepo";
+function firstNoRepoNoticeThisSession(folder, sessionId) {
+  if (!sessionId)
+    return true;
+  const path = join6(markerDir(), `${MARKER_PREFIX}${repoHash(folder)}-${sessionId}${NO_REPO_NOTICE_SUFFIX}`);
+  try {
+    writeFileSync3(path, "", { encoding: "utf-8", flag: "wx" });
+    return true;
+  } catch (err) {
+    return err.code !== "EEXIST";
+  }
+}
+function readDedupe(repoRoot, sessionId) {
+  const path = dedupePath(repoRoot, sessionId);
+  if (!existsSync3(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync6(path, "utf-8"));
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.base === "string" && typeof parsed.digest === "string") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeDedupe(repoRoot, sessionId, state) {
+  try {
+    writeFileSync3(dedupePath(repoRoot, sessionId), JSON.stringify(state), "utf-8");
+  } catch {
+  }
+}
+function digestChangeState(base, entries) {
+  const h = createHash("sha256");
+  h.update(base);
+  h.update("\0");
+  for (const e of [...entries].sort((a, b) => a.path.localeCompare(b.path))) {
+    h.update(e.path);
+    h.update("\0");
+    h.update(e.diffContent);
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+function orphanSweep(repoRoot, refKnown, keepSessionId, now = Date.now()) {
+  const dir = markerDir();
+  const hash2 = repoHash(repoRoot);
+  const keepName = keepSessionId ? markerFileName(repoRoot, keepSessionId) : markerFileName(repoRoot);
+  let names;
+  try {
+    names = readdirSync3(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (!name.startsWith(`${MARKER_PREFIX}${hash2}`) || !name.endsWith(MARKER_SUFFIX))
+      continue;
+    if (name === keepName)
+      continue;
+    const full = join6(dir, name);
+    let unusable = false;
+    try {
+      const ref = readFileSync6(full, "utf-8").trim();
+      if (!ref || !refKnown(ref))
+        unusable = true;
+    } catch {
+      unusable = true;
+    }
+    if (!unusable) {
+      try {
+        const age = now - statSync(full).mtimeMs;
+        if (age > MARKER_TTL_MS)
+          unusable = true;
+      } catch {
+        unusable = true;
+      }
+    }
+    if (unusable) {
+      const mid = name.slice(`${MARKER_PREFIX}${hash2}`.length, -MARKER_SUFFIX.length);
+      const sid = mid.startsWith("-") ? mid.slice(1) : void 0;
+      deleteMarker(repoRoot, sid);
+    }
+  }
+}
+
 // dist/seat-configuration.js
-import { existsSync as existsSync3, readFileSync as readFileSync6, realpathSync as realpathSync2 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync7, realpathSync as realpathSync2 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join6, relative as relative3, resolve } from "node:path";
+import { join as join7, relative as relative3, resolve } from "node:path";
 function gatherSeatConfiguration(repoRoot, read = readSeatConfiguration) {
   try {
     const facts = read(repoRoot);
@@ -17488,7 +17636,7 @@ function isPlainObject2(value) {
 function readSettingsFile(projectDir, rel) {
   let raw;
   try {
-    raw = readFileSync6(join6(projectDir, rel), "utf-8");
+    raw = readFileSync7(join7(projectDir, rel), "utf-8");
   } catch (err) {
     const code = err.code;
     const state = code === "ENOENT" || code === "ENOTDIR" ? "absent" : "unreadable";
@@ -17560,7 +17708,7 @@ function readPathStates(projectDir, repoRoot) {
   const status = getWiringStatus(HALFCYCLE_HOOK_WIRING_PATHS, projectDir);
   if (!status.ok)
     return unknown2();
-  const mapped = mapWiringStatus(status.value, prefix, HALFCYCLE_HOOK_WIRING_PATHS, (rel) => existsSync3(join6(projectDir, rel)));
+  const mapped = mapWiringStatus(status.value, prefix, HALFCYCLE_HOOK_WIRING_PATHS, (rel) => existsSync4(join7(projectDir, rel)));
   return mapped ?? unknown2();
 }
 function mapWiringStatus(output, prefix, paths, onDisk) {
@@ -17625,7 +17773,9 @@ async function evaluateEdit(reply, readSeat) {
     return;
   const repoRootResult = getRepoRoot(process.cwd());
   if (!repoRootResult.ok) {
-    reply.notice(localFaultText(`Could not find git repo root: ${repoRootResult.message}`));
+    if (firstNoRepoNoticeThisSession(process.cwd(), input.session_id)) {
+      reply.notice(localFaultText(`Could not find git repo root: ${repoRootResult.message}`));
+    }
     return;
   }
   const repoRoot = repoRootResult.value;
@@ -17740,127 +17890,6 @@ function readStdin() {
   });
 }
 
-// dist/hooks/marker.js
-import { createHash } from "node:crypto";
-import { existsSync as existsSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync3, unlinkSync as unlinkSync3, readdirSync as readdirSync3, statSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join as join7 } from "node:path";
-var MARKER_TTL_MS = 24 * 60 * 60 * 1e3;
-var MARKER_PREFIX = "halfcycle-session-";
-var MARKER_SUFFIX = ".ref";
-var DEDUPE_SUFFIX = ".eval";
-function markerDir() {
-  const raw = process.env["TMPDIR"] ?? tmpdir();
-  return raw.replace(/\/+$/, "");
-}
-function repoHash(repoRoot) {
-  return createHash("sha256").update(repoRoot).digest("hex").slice(0, 12);
-}
-function markerFileName(repoRoot, sessionId) {
-  const hash2 = repoHash(repoRoot);
-  const key = sessionId && sessionId.length > 0 ? `${hash2}-${sessionId}` : hash2;
-  return `${MARKER_PREFIX}${key}${MARKER_SUFFIX}`;
-}
-function markerPath(repoRoot, sessionId) {
-  return join7(markerDir(), markerFileName(repoRoot, sessionId));
-}
-function dedupePath(repoRoot, sessionId) {
-  const hash2 = repoHash(repoRoot);
-  const key = sessionId && sessionId.length > 0 ? `${hash2}-${sessionId}` : hash2;
-  return join7(markerDir(), `${MARKER_PREFIX}${key}${DEDUPE_SUFFIX}`);
-}
-function readMarker(repoRoot, sessionId) {
-  const path = markerPath(repoRoot, sessionId);
-  if (!existsSync4(path))
-    return null;
-  try {
-    return readFileSync7(path, "utf-8").trim() || null;
-  } catch {
-    return null;
-  }
-}
-function deleteMarker(repoRoot, sessionId) {
-  for (const path of [markerPath(repoRoot, sessionId), dedupePath(repoRoot, sessionId)]) {
-    try {
-      if (existsSync4(path))
-        unlinkSync3(path);
-    } catch {
-    }
-  }
-}
-function readDedupe(repoRoot, sessionId) {
-  const path = dedupePath(repoRoot, sessionId);
-  if (!existsSync4(path))
-    return null;
-  try {
-    const parsed = JSON.parse(readFileSync7(path, "utf-8"));
-    if (typeof parsed === "object" && parsed !== null && typeof parsed.base === "string" && typeof parsed.digest === "string") {
-      return parsed;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-function writeDedupe(repoRoot, sessionId, state) {
-  try {
-    writeFileSync3(dedupePath(repoRoot, sessionId), JSON.stringify(state), "utf-8");
-  } catch {
-  }
-}
-function digestChangeState(base, entries) {
-  const h = createHash("sha256");
-  h.update(base);
-  h.update("\0");
-  for (const e of [...entries].sort((a, b) => a.path.localeCompare(b.path))) {
-    h.update(e.path);
-    h.update("\0");
-    h.update(e.diffContent);
-    h.update("\0");
-  }
-  return h.digest("hex");
-}
-function orphanSweep(repoRoot, refKnown, keepSessionId, now = Date.now()) {
-  const dir = markerDir();
-  const hash2 = repoHash(repoRoot);
-  const keepName = keepSessionId ? markerFileName(repoRoot, keepSessionId) : markerFileName(repoRoot);
-  let names;
-  try {
-    names = readdirSync3(dir);
-  } catch {
-    return;
-  }
-  for (const name of names) {
-    if (!name.startsWith(`${MARKER_PREFIX}${hash2}`) || !name.endsWith(MARKER_SUFFIX))
-      continue;
-    if (name === keepName)
-      continue;
-    const full = join7(dir, name);
-    let unusable = false;
-    try {
-      const ref = readFileSync7(full, "utf-8").trim();
-      if (!ref || !refKnown(ref))
-        unusable = true;
-    } catch {
-      unusable = true;
-    }
-    if (!unusable) {
-      try {
-        const age = now - statSync(full).mtimeMs;
-        if (age > MARKER_TTL_MS)
-          unusable = true;
-      } catch {
-        unusable = true;
-      }
-    }
-    if (unusable) {
-      const mid = name.slice(`${MARKER_PREFIX}${hash2}`.length, -MARKER_SUFFIX.length);
-      const sid = mid.startsWith("-") ? mid.slice(1) : void 0;
-      deleteMarker(repoRoot, sid);
-    }
-  }
-}
-
 // dist/hooks/session-diff.js
 var STOP_HOOK_EVENT = {
   stop: "Stop",
@@ -17904,7 +17933,9 @@ async function runSessionDiff(input, kind, readSeat = readSeatConfiguration) {
 async function evaluateSession(input, kind, reply, readSeat) {
   const repoRootResult = getRepoRoot(process.cwd());
   if (!repoRootResult.ok) {
-    reply.notice(localFaultText(`Could not find git repo root: ${repoRootResult.message}`));
+    if (firstNoRepoNoticeThisSession(process.cwd(), input.session_id)) {
+      reply.notice(localFaultText(`Could not find git repo root: ${repoRootResult.message}`));
+    }
     return;
   }
   const repoRoot = repoRootResult.value;
@@ -18376,6 +18407,7 @@ async function refreshCredentialToken(opts) {
   return { token: refreshed.token };
 }
 var CHECKED_SOURCES = /* @__PURE__ */ new Set(["startup", "resume"]);
+var CONNECTED_SENTENCE = "Halfcycle connected.";
 var INITIALIZE_BODY = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} });
 function registeredMcpUrl(projectRoot) {
   let parsed;
@@ -18461,7 +18493,8 @@ async function checkConnection(renewedToken, opts) {
   if (CREDENTIAL_PLACEHOLDERS.includes(bearer)) {
     return PLACEHOLDER_SENTENCES[bearer];
   }
-  return probeDelivery(url2, bearer, opts.fetchFn ?? globalThis.fetch, opts.checkDeadlineMs ?? CONNECTION_CHECK_DEADLINE_MS);
+  const outcome = await probeDelivery(url2, bearer, opts.fetchFn ?? globalThis.fetch, opts.checkDeadlineMs ?? CONNECTION_CHECK_DEADLINE_MS);
+  return outcome ?? CONNECTED_SENTENCE;
 }
 function defaultWriteErr2(text) {
   process.stderr.write(text);

package/commands/halfcycle-setup.md

@@ -4,8 +4,8 @@ description: Set up a repository for a Halfcycle engagement
 
 Resolve `/halfcycle-setup` for this engagement's current state, execute what comes back, report that the step ran, and resolve again — repeating until the response says there is nothing left (`hasNextStep` false); pausing for a human answer is not the end of the run. Do not improvise the procedure. Say where things stand at the boundaries of the run — when it starts, when it moves to a new layer, and when it ends — rather than on every turn, and pause only where a step asks you to. At one of those boundaries, and at most once per run, point them at this project's own page on the web and say what is there: how the project is going, the agents working on it once there are any, and their other projects alongside it. Use the address this install already records for the project's page rather than building one from an example, and give them the address itself — a page they are told about but cannot reach is worse than not mentioning it. Some steps of the Halfcycle method are judged by Halfcycle rather than by this session, or need a person to do something outside this session, so a quiet run is not a claim that nothing was due — say so when a run ends. Everything you say to the person is in plain words. Name the Halfcycle method the first time and say what it is in the same breath — the process that will guide the two of you through building this — because bare "the method" means nothing to someone who has not met it. After that, talk about their product and never about how any of this works underneath: no paths or files of ours, no hooks, settings, commands, layers or step names, and never Halfcycle's own machinery as the subject of a sentence. Say what now exists, what it is for, and what you need from them, in their terms. The one thing you never soften and never leave out is what did NOT happen — say that plainly too. If you are asked to jump ahead: when that is what comes next anyway, just do it; when Halfcycle refuses, relay its reason word for word and invent no procedure of your own; when it can be served but skips something, do it and say what is being skipped and what that costs. Coming back later is fine — a fresh session re-orients from what this project has recorded, so ask to carry on in plain words and you get the right next step and where things stand.
 
-If resolution fails, report exactly this and stop:
+If resolution fails, report whichever applies and stop:
 
 > Halfcycle didn't answer for `/halfcycle-setup`. **Nothing has run.**
-> Allow any Halfcycle tool you declined. If Claude Code does not trust this folder yet, open
-> it there and accept the workspace-trust prompt. Then run this again, or retry once online.
+> Service error — Halfcycle's service is down, try again shortly. Tool declined — run `/mcp` and reconnect it, then run this again.
+> Folder not yet trusted — Claude Code does not trust this folder yet, open it there and accept the workspace-trust prompt, then run this again.