fix(daemon): address PR review — strict orphan match, stale-path repair, docs sync

Orphan detection now requires a hack executable (basename hack/hack-*
or a bun dev-tree invocation) — a bare substring match could have
terminated unrelated processes. Plist repair also normalizes programs
that still exist but differ from the current stable resolution
(surviving homebrew Cellar paths would relaunch the old binary in an
incompatible-daemon loop). Instruction source lists the tickets/
ignore entry; surfaces resynced.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: roodboi

.codex/skills/hack-cli/SKILL.md

@@ -65,7 +65,7 @@ Use `hack` as the primary interface for local-first development.
 - Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
-- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
+- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`, `tickets/`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
 
 ## Linked git worktrees
 

.cursor/rules/hack.mdc

@@ -29,7 +29,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 - Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
-- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
+- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`, `tickets/`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
 
 ## Linked git worktrees
 

AGENTS.md

@@ -257,7 +257,7 @@ Project files (managed vs generated):
 - Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
-- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
+- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`, `tickets/`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
 
 Linked git worktrees:
 - Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.

CLAUDE.md

@@ -127,7 +127,7 @@ Project files (managed vs generated):
 - Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
 - Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).
 - Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.
-- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
+- Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`, `tickets/`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).
 
 Linked git worktrees:
 - Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.

src/agents/instruction-source.ts

@@ -113,7 +113,7 @@ export const INSTRUCTION_SECTIONS: readonly InstructionSection[] = [
       "Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.",
       "Managed via CLI: `.hack/.internal/extra-hosts.json` (use `hack internal extra-hosts ...` commands).",
       "Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.",
-      "Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).",
+      "Ignore rules: hack owns a committed `.hack/.gitignore` (self-healing on init/up) covering machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`, `tickets/`); keep it committed, and if generated files leaked into git, `hack doctor --fix` untracks them (files stay on disk).",
     ],
   },
   {

src/daemon/launchd.ts

@@ -249,13 +249,23 @@ export async function repairLaunchdProgramIfInvalid(opts: {
     return "not-installed";
   }
   const program = extractLaunchdProgramPath({ plistText });
-  const valid =
+  const invocation = await resolveHackInvocation();
+  const resolved = await resolveLaunchdHackBinPath({ invocation });
+  const exists =
     program !== null &&
     !isVirtualExecutablePath(program) &&
     (await pathExists(program));
+  // A program that still exists can still be stale: a versioned homebrew
+  // Cellar path survives until brew cleanup, so kickstart would relaunch
+  // the OLD binary forever (incompatible-daemon loop). Normalize to the
+  // current stable resolution whenever it differs.
+  const valid = exists && (resolved === null || program === resolved);
   if (valid) {
     return "ok";
   }
+  if (!exists && resolved === null) {
+    return "failed";
+  }
 
   const result = await installLaunchdService({
     paths: opts.paths,

src/daemon/process.ts

@@ -101,6 +101,9 @@ export async function findOrphanDaemonProcesses(opts: {
     if (!command.includes(DAEMON_COMMAND_MARKER)) {
       continue;
     }
+    if (!isHackDaemonCommand({ command })) {
+      continue;
+    }
     if (pid === opts.trackedPid || pid === process.pid) {
       continue;
     }
@@ -109,6 +112,26 @@ export async function findOrphanDaemonProcesses(opts: {
   return orphans;
 }
 
+/**
+ * True when the process command line is actually a hack daemon: the
+ * executable's basename must be `hack`/`hack-*` (or a `bun .../hack`
+ * dev-tree invocation). A bare substring match on the daemon arguments
+ * would also kill unrelated processes that merely mention them.
+ */
+function isHackDaemonCommand(opts: { readonly command: string }): boolean {
+  const firstToken = opts.command.trim().split(/\s+/)[0] ?? "";
+  const base = firstToken.split("/").pop()?.toLowerCase() ?? "";
+  if (base === "hack" || base.startsWith("hack-")) {
+    return true;
+  }
+  if (base === "bun") {
+    const secondToken = opts.command.trim().split(/\s+/)[1] ?? "";
+    const secondBase = secondToken.split("/").pop()?.toLowerCase() ?? "";
+    return secondBase === "index.ts" || secondBase.startsWith("hack");
+  }
+  return false;
+}
+
 async function listProcessTable(): Promise<readonly string[]> {
   const proc = Bun.spawn(["ps", "-axo", "pid=,command="], {
     stdout: "pipe",

tests/agent-instruction-source.test.ts

@@ -103,6 +103,9 @@ test("tickets appear at most once, only as an optional extension", () => {
   for (const [surface, rendered] of Object.entries(RENDERED_SURFACES)) {
     const ticketLines = rendered
       .split("\n")
+      // The gitignore pattern literal `tickets/` (managed-files section) is
+      // a filename, not tickets promotion — the thing this test guards.
+      .map((line) => line.replaceAll("`tickets/`", ""))
       .filter((line) => /ticket/i.test(line));
     expect(
       ticketLines.length,

tests/daemon-orphan.test.ts

@@ -25,16 +25,18 @@ test("all daemon processes are orphans when no pid is tracked", async () => {
   expect(orphans).toEqual([123, 456]);
 });
 
-test("ignores its own pid and requires the exact daemon marker", async () => {
+test("ignores its own pid, non-hack executables, and near-miss commands", async () => {
   const orphans = await findOrphanDaemonProcesses({
     trackedPid: null,
     psLines: [
       `  ${process.pid} hack daemon start --foreground`,
       "  789 tail -f daemon-start-foreground.log",
       "  790 node something daemon start --foreground",
+      "  791 /tmp/hack-repo/bin/hack-dev daemon start --foreground",
+      "  792 bun /tmp/hack-repo/index.ts daemon start --foreground",
     ],
   });
-  expect(orphans).toEqual([790]);
+  expect(orphans).toEqual([791, 792]);
 });
 
 import {