@cbartens/bkit 5.1.0 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +90 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  136. package/.bkit/templates/.prettierignore +1 -1
  137. package/.bkit/templates/context/bkit-expo.md +22 -13
  138. package/.bkit/templates/context/bkit-github.md +20 -6
  139. package/.bkit/templates/context/bkit-inngest.md +10 -4
  140. package/.bkit/templates/context/bkit-maestro.md +5 -5
  141. package/.bkit/templates/context/bkit-playwright.md +3 -3
  142. package/.bkit/templates/context/bkit-sentry.md +6 -5
  143. package/.bkit/templates/context/bkit-stripe.md +31 -8
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  145. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  147. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  148. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  149. package/.bkit/templates/slop-scan.config.json +7 -2
  150. package/CHANGELOG.md +42 -0
  151. package/LICENSE.md +21 -161
  152. package/README.md +58 -28
  153. package/dist/checks/after/auth.js +28 -0
  154. package/dist/checks/after/github.js +4 -4
  155. package/dist/checks/after/index.js +29 -45
  156. package/dist/checks/after/managed.js +40 -1
  157. package/dist/checks/before/index.js +5 -4
  158. package/dist/checks/before/mcp.js +53 -53
  159. package/dist/checks/status-holes.js +1 -1
  160. package/dist/checks/tips/catalogue.js +297 -0
  161. package/dist/checks/tips/detect.js +130 -0
  162. package/dist/checks/tips/index.js +146 -0
  163. package/dist/cli.js +47 -9
  164. package/dist/commands/install/doctor.js +5 -1
  165. package/dist/commands/install/install.js +27 -7
  166. package/dist/commands/install/uninstall.js +31 -16
  167. package/dist/commands/install/upgrade.js +15 -32
  168. package/dist/commands/launch.js +27 -11
  169. package/dist/commands/tips.js +10 -0
  170. package/dist/commands/workflow/runs.js +52 -16
  171. package/dist/commands/workflow/runtime.js +8 -0
  172. package/dist/commands/workflow/steps.js +1 -0
  173. package/dist/commands/workflow/tests.js +541 -4
  174. package/dist/commands/workflow/workstreams.js +4 -4
  175. package/dist/install/cloud-env.js +3 -14
  176. package/dist/install/hosts.js +22 -0
  177. package/dist/install/managed-block.js +36 -0
  178. package/dist/install/manifest.js +45 -4
  179. package/dist/install/modules/antigravity.js +8 -7
  180. package/dist/install/modules/claude.js +6 -6
  181. package/dist/install/modules/cloud.js +2 -2
  182. package/dist/install/modules/codex.js +5 -5
  183. package/dist/install/modules/core.js +14 -5
  184. package/dist/install/modules/cursor.js +6 -6
  185. package/dist/install/modules/opencode.js +4 -4
  186. package/dist/install/payload-links.js +5 -5
  187. package/dist/install/placeholders.js +1 -1
  188. package/dist/install/version-file.js +12 -3
  189. package/dist/install/write.js +61 -2
  190. package/dist/shared/package-roots.js +8 -11
  191. package/package.json +4 -6
  192. package/.bkit/core/LICENSE.md +0 -149
  193. package/.bkit/shared/LICENSE.md +0 -22
  194. package/.bkit/templates/LICENSE.md +0 -22
@@ -57,6 +57,7 @@ import {
57
57
  parseIssueTracker,
58
58
  } from "../../install/manifest.js";
59
59
  import { OPTIN_MODULES } from "../../install/manifest.js";
60
+ import { detectInstalledHostModules } from "../../install/hosts.js";
60
61
  import { detectInstalledModules } from "./check.js";
61
62
  import { remapTemplateDest } from "../../install/template-copies.js";
62
63
  import {
@@ -528,22 +529,6 @@ export function updateCanonicalHashesAfterUpgrade(
528
529
  writeBkitVersion(versionFile, updated);
529
530
  }
530
531
 
531
- /**
532
- * Detect which host modules a consumer has installed, by the presence of each host's
533
- * source-rendered agents directory. Used by `bkit upgrade` to re-render only the hosts
534
- * the consumer installed — never force-creating an opencode/cursor tree.
535
- */
536
- export function detectInstalledHostModules(cwd: string): Set<ModuleFlag> {
537
- const mods = new Set<ModuleFlag>();
538
- if (fs.existsSync(path.join(cwd, ".claude", "agents"))) mods.add("claude");
539
- if (fs.existsSync(path.join(cwd, ".cursor", "agents"))) mods.add("cursor");
540
- if (fs.existsSync(path.join(cwd, ".opencode", "agents"))) mods.add("opencode");
541
- if (fs.existsSync(path.join(cwd, ".codex", "agents"))) mods.add("codex");
542
- if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
543
- mods.add("antigravity");
544
- return mods;
545
- }
546
-
547
532
  /**
548
533
  * Resolve the newest published @cbartens/bkit version from the registry for
549
534
  * `bkit upgrade --latest`. Shells out to `pnpm view` (honours the consumer's
@@ -736,8 +721,6 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
736
721
  if (ent.isDirectory()) {
737
722
  collectPayload(entAbs, entRel, skipTopDirs);
738
723
  } else if (ent.isFile()) {
739
- // Each payload root's LICENSE.md is package metadata, never an install source.
740
- if (ent.name === "LICENSE.md") continue;
741
724
  // Single shared dotfile remap (gitignore → .gitignore, npmignore → .npmignore).
742
725
  const relPath = remapTemplateDest(entRel);
743
726
  // `.claude/bkit-cloud.md` + `.cursor/bkit-cloud.md` are GENERATED output files
@@ -748,15 +731,22 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
748
731
  // (host-gated, non-dry-run).
749
732
  if (relPath === CLAUDE_CLOUD_RELPATH || relPath === CURSOR_CLOUD_RELPATH) continue;
750
733
  if (relPath === MCP_ROOT_RELPATH || relPath === CURSOR_MCP_RELPATH) continue;
751
- // Skip opt-in-module files the consumer hasn't opted into (dest absent).
734
+ const entry = entryByPath.get(relPath);
735
+ const ownerModule = entry?.module;
736
+ // Skip opt-in-module files the consumer hasn't opted into: dest absent and the owning
737
+ // module not detected as installed. A detected opt-in host (opencode / codex /
738
+ // antigravity) gets the files a newer release adds; `cloud` has no install sentinel,
739
+ // so its files upgrade only when present. opencode.json is created only when its
740
+ // provider resolves — never written with raw `@@OPENCODE_*@@` sentinels.
752
741
  if (optInPaths.has(relPath) && !fs.existsSync(path.join(process.cwd(), relPath))) {
753
- continue;
742
+ const hostInstalled = ownerModule !== undefined && installedModules.has(ownerModule);
743
+ if (!hostInstalled || (relPath === OPENCODE_JSON_RELPATH && !upgradeOpencodeProvider)) {
744
+ continue;
745
+ }
754
746
  }
755
- const entry = entryByPath.get(relPath);
756
747
  // Skip host-module files when that module is not installed — upgrade updates
757
748
  // only what the consumer opted into, never force-creating a new module. opt-ins are
758
- // handled by the dest-presence check above; core + entry-less files always pass.
759
- const ownerModule = entry?.module;
749
+ // handled by the check above; core + entry-less files always pass.
760
750
  if (
761
751
  ownerModule &&
762
752
  ownerModule !== "core" &&
@@ -805,11 +795,8 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
805
795
 
806
796
  // Payload view links — the same sync install runs (`.bkit/core` + `.bkit/shared`
807
797
  // point into the installed package). Never clobbers a real directory; a platform
808
- // refusal is reported, never fatal. Throwaway WriteSet: links carry no hash.
809
- const linkChanges = syncPayloadLinks(process.cwd(), {
810
- dryRun: upgradeFlags.dryRun,
811
- ws: { writes: [] },
812
- });
798
+ // refusal is reported, never fatal. Links carry no hash.
799
+ const linkChanges = syncPayloadLinks(process.cwd(), { dryRun: upgradeFlags.dryRun });
813
800
  const linkReport = formatPayloadLinkChanges(linkChanges);
814
801
  if (linkReport) console.log(`${LOG_PREFIX} ${linkReport}`);
815
802
 
@@ -86,11 +86,32 @@ export function isAlreadyRunning(binaryPath: string): boolean {
86
86
  return !result.error && result.status === 0 && result.stdout.trim().length > 0;
87
87
  }
88
88
 
89
+ /** `pgrep -f` pattern for OpenCode 2.0's shared background server (`<dir>/opencode serve --service`). */
90
+ const OPENCODE_SERVER_PATTERN = "(^|/)opencode serve( |$)";
91
+
92
+ /**
93
+ * Return true if OpenCode 2.0's shared background server (`opencode serve`) is running.
94
+ * It outlives the desktop app and every client attaches to it, so it holds the stale env.
95
+ */
96
+ export function isOpencodeServerRunning(): boolean {
97
+ return isAlreadyRunning(OPENCODE_SERVER_PATTERN);
98
+ }
99
+
100
+ const OPENCODE_SERVER_ADVICE =
101
+ ` OpenCode 2.0 runs one shared background server for every client (TUI, web,\n` +
102
+ ` desktop) and captures its environment once, at first start. A newly opened\n` +
103
+ ` window talks to that server and still sees the OLD env, so the per-repo tokens\n` +
104
+ ` in .bkit/.env are not picked up. Stop the shared server, then re-launch:\n` +
105
+ ` opencode service stop && pnpm bkit opencode\n` +
106
+ ` (that stops every opencode window, not just this one; quitting the app fully\n` +
107
+ ` and re-running works too)`;
108
+
89
109
  /**
90
110
  * Launch `app` with .bkit/.env merged into its environment.
91
111
  *
92
112
  * - Loads `.bkit/.env` from `cwd` and merges into process.env (process.env wins).
93
- * - Detects an already-running instance via pgrep; warns + exits non-zero if found
113
+ * - Detects an already-running instance via pgrep (for opencode also the 2.0 shared
114
+ * background server `opencode serve`); warns if found
94
115
  * (the running process will not inherit the new env even if the binary hands off).
95
116
  * - For Cursor: passes `cwd` as a positional arg so it opens the repo folder.
96
117
  * - Spawns detached so the terminal is not blocked by the GUI app.
@@ -105,21 +126,22 @@ export async function launchApp(app: LaunchApp, cwd: string): Promise<void> {
105
126
  }
106
127
  const { binPath } = resolved;
107
128
 
108
- if (isAlreadyRunning(binPath)) {
129
+ const appRunning = isAlreadyRunning(binPath);
130
+ const serverRunning = app === "opencode" && isOpencodeServerRunning();
131
+
132
+ if (appRunning) {
109
133
  console.warn(
110
134
  `[bkit] ${app} is already running — opening folder in a new window, but the\n` +
111
135
  `environment from .bkit/.env will NOT take effect (the running process keeps\n` +
112
136
  `its original env). If you need per-repo tokens, quit ${app} fully (Cmd+Q)\n` +
113
137
  `and re-run: pnpm bkit ${app}` +
114
- (app === "opencode"
115
- ? `\n\n OpenCode 2.0 runs one shared background server for every client (TUI, web,\n` +
116
- ` desktop) and captures its environment once, at first start. A newly opened\n` +
117
- ` window talks to that server and still sees the OLD env, so the per-repo tokens\n` +
118
- ` in .bkit/.env are not picked up. Stop the shared server, then re-launch:\n` +
119
- ` opencode service stop && pnpm bkit opencode\n` +
120
- ` (that stops every opencode window, not just this one; quitting the app fully\n` +
121
- ` and re-running works too)`
122
- : ""),
138
+ (app === "opencode" ? `\n\n${OPENCODE_SERVER_ADVICE}` : ""),
139
+ );
140
+ } else if (serverRunning) {
141
+ console.warn(
142
+ `[bkit] the opencode background server (opencode serve) is already running — the\n` +
143
+ `environment from .bkit/.env will NOT take effect (the server keeps the env it\n` +
144
+ `started with, even though the desktop app itself is not open).\n\n${OPENCODE_SERVER_ADVICE}`,
123
145
  );
124
146
  }
125
147
 
@@ -0,0 +1,16 @@
1
+ // commands/tips.ts — `bkit tips [--workflow=<name>] [--all]`: print the setup tips that
2
+ // apply to this repo. Each workflow passes its name at its close and gets the one tip that
3
+ // matters most there; bare `bkit tips` prints the top three. Local checks only, no
4
+ // network; prints nothing when no tip fires; exits 0.
5
+
6
+ import type { ComplyPhase } from "../cli.js";
7
+ import { collectTips, formatTips } from "../checks/tips/index.js";
8
+
9
+ export function runTipsCommand(
10
+ all: boolean,
11
+ workflow: ComplyPhase | null,
12
+ cwd: string = process.cwd(),
13
+ ): void {
14
+ const output = formatTips(collectTips(cwd).tips, { all, workflow });
15
+ if (output) console.log(output);
16
+ }
@@ -1077,8 +1077,24 @@ const INTERVAL_FLAG: FlagSpec = {
1077
1077
  help: "seconds between polls (>= 1)",
1078
1078
  };
1079
1079
 
1080
- const deps = (ctx: RunContext) => ({
1081
- gh: (args: string[]) => runGh(ctx.cwd, args),
1080
+ /**
1081
+ * `gh` pinned to `repo`: `--repo` is appended to every subcommand that takes it.
1082
+ * `gh api` is left alone because its path already names the repo. No `repo` = `gh` unchanged.
1083
+ */
1084
+ export function repoScopedGh(gh: Gh, repo: string | undefined): Gh {
1085
+ if (repo === undefined) return gh;
1086
+ return (args) => (args[0] === "api" ? gh(args) : gh([...args, "--repo", repo]));
1087
+ }
1088
+
1089
+ /** Whether `--repo` names a repo other than the checkout's own (local git then describes the wrong repo). */
1090
+ function isForeignRepo(cwd: string, repo: string | undefined): boolean {
1091
+ return (
1092
+ repo !== undefined && resolveOwnerRepo(cwd)?.ownerRepo.toLowerCase() !== repo.toLowerCase()
1093
+ );
1094
+ }
1095
+
1096
+ const deps = (ctx: RunContext, repo?: string) => ({
1097
+ gh: repoScopedGh((args: string[]) => runGh(ctx.cwd, args), repo),
1082
1098
  sleep: realSleep,
1083
1099
  log: ctx.log,
1084
1100
  });
@@ -1423,10 +1439,25 @@ function runGate(ctx: RunContext): number {
1423
1439
  const snapshot = str(f.snapshot);
1424
1440
  if (snapshot !== undefined) {
1425
1441
  const info = pr?.kind === "ok" ? pr.pr : undefined;
1426
- const dev = git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "";
1427
- const ancestor = runGit(ctx.cwd, ["merge-base", "--is-ancestor", "origin/dev", head]).ok;
1442
+ const repoFlag = str(f.repo);
1443
+ const foreign = isForeignRepo(ctx.cwd, repoFlag);
1444
+ // A foreign repo's dev and ancestry come from the API: the checkout's origin/dev is another repo's.
1445
+ let dev: string;
1446
+ let ancestor: boolean;
1447
+ if (foreign && repoFlag !== undefined) {
1448
+ const devRes = gh(["api", `repos/${repoFlag}/commits/dev`, "--jq", ".sha"]);
1449
+ dev = devRes.ok ? devRes.stdout.trim() : "";
1450
+ const cmp = gh(["api", `repos/${repoFlag}/compare/dev...${head}`, "--jq", ".status"]);
1451
+ ancestor = cmp.ok && ["ahead", "identical"].includes(cmp.stdout.trim());
1452
+ } else {
1453
+ dev = git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "";
1454
+ ancestor = runGit(ctx.cwd, ["merge-base", "--is-ancestor", "origin/dev", head]).ok;
1455
+ }
1428
1456
  const ciWorkflow = readBkitConfig(root).ciWorkflow;
1429
- const runs = gh([
1457
+ const runs = repoScopedGh(
1458
+ gh,
1459
+ repoFlag,
1460
+ )([
1430
1461
  "run",
1431
1462
  "list",
1432
1463
  "--branch",
@@ -1528,7 +1559,9 @@ function devRequiresChecks(gh: Gh, repo: string): boolean {
1528
1559
 
1529
1560
  async function runRevalidate(ctx: RunContext): Promise<number> {
1530
1561
  const f = ctx.flags;
1531
- const d = deps(ctx);
1562
+ const repoFlag = str(f.repo);
1563
+ const d = deps(ctx, repoFlag);
1564
+ const foreign = isForeignRepo(ctx.cwd, repoFlag);
1532
1565
  const branch = String(f.branch);
1533
1566
  const entry = String(f.entryHead);
1534
1567
  const codeHead = String(f.codeHead);
@@ -1536,8 +1569,8 @@ async function runRevalidate(ctx: RunContext): Promise<number> {
1536
1569
  if (!["head-move", "gate-refusal"].includes(reason))
1537
1570
  throw new CommandError(EXIT.USAGE, "--reason must be head-move or gate-refusal");
1538
1571
  const status = path.resolve(ctx.cwd, String(f.file));
1539
- runGit(ctx.cwd, ["fetch", "origin", branch]);
1540
- const pr = probePr(ctx.cwd, { number: String(f.pr), state: "open", repo: str(f.repo) });
1572
+ if (!foreign) runGit(ctx.cwd, ["fetch", "origin", branch]);
1573
+ const pr = probePr(ctx.cwd, { number: String(f.pr), state: "open", repo: repoFlag });
1541
1574
  if (pr.kind === "unavailable") {
1542
1575
  ctx.log(pr.message);
1543
1576
  return EXIT.USE_MCP;
@@ -1552,14 +1585,22 @@ async function runRevalidate(ctx: RunContext): Promise<number> {
1552
1585
  // CI must pass at the code head while the PR head adds bookkeeping only and dev
1553
1586
  // demands no status checks; otherwise at the PR head.
1554
1587
  let validated = codeHead;
1555
- const book = onlyBookkeeping(checkoutRoot(ctx.cwd), {
1556
- month: String(f.month),
1557
- fid: String(f.fid),
1558
- from: codeHead,
1559
- to: current,
1560
- });
1561
- if (!book.ok) validated = current;
1562
- const repo = str(f.repo) ?? resolveOwnerRepo(ctx.cwd)?.ownerRepo;
1588
+ if (foreign) {
1589
+ // The bookkeeping diff reads the checkout's git, which is not the named repo's history.
1590
+ ctx.log(
1591
+ `--repo ${repoFlag} is not this checkout's repo — bookkeeping diff skipped, validating at the PR head ${current}`,
1592
+ );
1593
+ validated = current;
1594
+ } else {
1595
+ const book = onlyBookkeeping(checkoutRoot(ctx.cwd), {
1596
+ month: String(f.month),
1597
+ fid: String(f.fid),
1598
+ from: codeHead,
1599
+ to: current,
1600
+ });
1601
+ if (!book.ok) validated = current;
1602
+ }
1603
+ const repo = repoFlag ?? resolveOwnerRepo(ctx.cwd)?.ownerRepo;
1563
1604
  if (repo !== undefined && devRequiresChecks(d.gh, repo)) {
1564
1605
  ctx.log(`dev requires status checks — validating at the PR head ${current}`);
1565
1606
  validated = current;
@@ -17,6 +17,9 @@
17
17
  // CLAUDE_CODE_REMOTE truthy CLOUD_CLAUDE
18
18
  // GITHUB_ACTIONS or CI truthy GITHUB_ACTION
19
19
  // otherwise LOCAL
20
+ //
21
+ // `runtimeHeadless` (no human attends the session) is derived from `runtime`, never
22
+ // stored on the row.
20
23
 
21
24
  import * as fs from "node:fs";
22
25
  import * as path from "node:path";
@@ -68,6 +71,7 @@ export interface RuntimeTable {
68
71
  runtime: Runtime;
69
72
  runtimeWorktrees: boolean;
70
73
  runtimeDevPushes: boolean;
74
+ runtimeHeadless: boolean;
71
75
  runtimeGithubCli: boolean;
72
76
  runtimeGithubCliExit: number;
73
77
  runtimeGithubCliErr: string;
@@ -108,6 +112,10 @@ export function classify(env: NodeJS.ProcessEnv, root: string, log: (m: string)
108
112
  const capable = (runtime: Runtime) =>
109
113
  runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
110
114
 
115
+ /** No human attends the session: a runner, a triggered Cursor agent, or a runtime bkit cannot place. */
116
+ const headless = (runtime: unknown) =>
117
+ runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR" || runtime === "UNKNOWN";
118
+
111
119
  /** The full table: classification, default capabilities, and the one live gh probe. */
112
120
  export function detect(cwd: string, root: string, log: (m: string) => void): RuntimeTable {
113
121
  const runtime = classify(process.env, root, log);
@@ -120,6 +128,7 @@ export function detect(cwd: string, root: string, log: (m: string) => void): Run
120
128
  runtime,
121
129
  runtimeWorktrees: capable(runtime),
122
130
  runtimeDevPushes: capable(runtime),
131
+ runtimeHeadless: headless(runtime),
123
132
  runtimeGithubCli: ok,
124
133
  runtimeGithubCliExit: gh.status,
125
134
  runtimeGithubCliErr: err,
@@ -167,6 +176,8 @@ const TABLE_OUTPUT = {
167
176
  runtime: RUNTIMES.join(" | "),
168
177
  runtimeWorktrees: "may mint git worktrees (default per runtime)",
169
178
  runtimeDevPushes: "may push dev (a default, never probed)",
179
+ runtimeHeadless:
180
+ "no human attends the session (GITHUB_ACTION | CLOUD_CURSOR | UNKNOWN); derived from runtime",
170
181
  runtimeGithubCli: "gh auth status succeeded",
171
182
  runtimeGithubCliExit: "gh auth status exit code (127 when gh is not on PATH)",
172
183
  runtimeGithubCliErr: "last non-empty line of gh auth status stderr",
@@ -284,6 +295,7 @@ export const runtimeCommand: CommandSpec = {
284
295
  runtime: row.runtime,
285
296
  runtimeWorktrees: row.runtimeWorktrees,
286
297
  runtimeDevPushes: row.runtimeDevPushes,
298
+ runtimeHeadless: headless(row.runtime),
287
299
  runtimeGithubCli: row.runtimeGithubCli,
288
300
  runtimeGithubCliExit:
289
301
  typeof row.runtimeGithubCliExit === "number" ? row.runtimeGithubCliExit : null,
@@ -268,6 +268,7 @@ type RowField = "attempt" | "strategy" | "scope";
268
268
  * calls (a finish call's `--agent` writes `strategy` when its prompt declares one).
269
269
  */
270
270
  export const ROW_FIELDS: Record<string, readonly RowField[]> = {
271
+ "design/design-grill": ["attempt"],
271
272
  "design/design-brainstorm-ideate": ["attempt"],
272
273
  "design/design-generate": ["attempt"],
273
274
  "design/design-review": ["attempt"],