@cbartens/bkit 5.0.3 → 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 (212) hide show
  1. package/.bkit/README.md +14 -10
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +93 -0
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +137 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  6. package/.bkit/core/.agents/rules.md +10 -6
  7. package/.bkit/core/.agents/shortcuts.md +73 -0
  8. package/.bkit/core/.agents/skills.md +5 -3
  9. package/.bkit/core/.bkit/LICENSE.md +18 -140
  10. package/.bkit/core/.bkit/README.md +13 -9
  11. package/.bkit/core/.bkit/cloud.md +12 -15
  12. package/.bkit/core/.bkit/comparison.md +68 -16
  13. package/.bkit/core/.bkit/install.md +36 -11
  14. package/.bkit/core/.bkit/jsonl.md +0 -1
  15. package/.bkit/core/.bkit/prompts.md +83 -81
  16. package/.bkit/core/.bkit/providers.md +110 -28
  17. package/.bkit/core/.bkit/templates.md +42 -13
  18. package/.bkit/core/.bkit/workflows.md +64 -42
  19. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  20. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  21. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  22. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  24. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  26. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  27. package/.bkit/core/AGENTS.md +11 -0
  28. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  29. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  30. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  31. package/.bkit/core/engine/checks/after/github.ts +4 -4
  32. package/.bkit/core/engine/checks/after/index.ts +36 -50
  33. package/.bkit/core/engine/checks/after/managed.ts +44 -1
  34. package/.bkit/core/engine/checks/before/index.ts +5 -4
  35. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  36. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  37. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  38. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  39. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  40. package/.bkit/core/engine/cli.ts +82 -18
  41. package/.bkit/core/engine/commands/install/check.ts +2 -0
  42. package/.bkit/core/engine/commands/install/doctor.ts +14 -1
  43. package/.bkit/core/engine/commands/install/install.ts +59 -9
  44. package/.bkit/core/engine/commands/install/uninstall.ts +59 -34
  45. package/.bkit/core/engine/commands/install/upgrade.ts +30 -28
  46. package/.bkit/core/engine/commands/launch.ts +33 -11
  47. package/.bkit/core/engine/commands/tips.ts +16 -0
  48. package/.bkit/core/engine/commands/workflow/prs.ts +20 -2
  49. package/.bkit/core/engine/commands/workflow/runs.ts +82 -18
  50. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  51. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  52. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  53. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  54. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  55. package/.bkit/core/engine/install/hosts.ts +21 -0
  56. package/.bkit/core/engine/install/managed-block.ts +36 -0
  57. package/.bkit/core/engine/install/manifest.ts +83 -5
  58. package/.bkit/core/engine/install/modules/antigravity.ts +266 -0
  59. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  60. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  61. package/.bkit/core/engine/install/modules/codex.ts +8 -5
  62. package/.bkit/core/engine/install/modules/core.ts +30 -10
  63. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  64. package/.bkit/core/engine/install/modules/index.ts +33 -6
  65. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  66. package/.bkit/core/engine/install/payload-links.ts +6 -10
  67. package/.bkit/core/engine/install/placeholders.ts +1 -1
  68. package/.bkit/core/engine/install/version-file.ts +17 -9
  69. package/.bkit/core/engine/install/write.ts +68 -1
  70. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  71. package/.bkit/core/engine/render/hosts.ts +174 -1
  72. package/.bkit/core/engine/render/models.ts +10 -0
  73. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  74. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  75. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  76. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  77. package/.bkit/core/hooks/guardrails-read.js +23 -0
  78. package/.bkit/core/hooks/readguard-engine.js +259 -0
  79. package/.bkit/core/hooks/readguard-payload.js +67 -0
  80. package/.bkit/core/prompts/bkit-audit-generate.md +2 -1
  81. package/.bkit/core/prompts/bkit-build-challenge-1.md +2 -1
  82. package/.bkit/core/prompts/bkit-build-challenge-2.md +2 -1
  83. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +2 -1
  84. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +2 -1
  85. package/.bkit/core/prompts/bkit-build-challenge-tests.md +2 -1
  86. package/.bkit/core/prompts/bkit-build-install-skills.md +7 -5
  87. package/.bkit/core/prompts/bkit-build-plan-current.md +2 -1
  88. package/.bkit/core/prompts/bkit-build-plan-execute.md +6 -2
  89. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +2 -1
  90. package/.bkit/core/prompts/bkit-build-plan-verify.md +12 -4
  91. package/.bkit/core/prompts/bkit-build-summary.md +2 -1
  92. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -1
  93. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +2 -1
  94. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +2 -1
  95. package/.bkit/core/prompts/bkit-debug-failure-soak.md +2 -1
  96. package/.bkit/core/prompts/bkit-debug-summary.md +2 -1
  97. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +2 -1
  98. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +2 -1
  99. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +2 -1
  100. package/.bkit/core/prompts/bkit-design-generate.md +10 -5
  101. package/.bkit/core/prompts/bkit-design-organise.md +2 -1
  102. package/.bkit/core/prompts/bkit-design-review-1.md +2 -1
  103. package/.bkit/core/prompts/bkit-design-review-2.md +2 -1
  104. package/.bkit/core/prompts/bkit-design-spike.md +2 -1
  105. package/.bkit/core/prompts/bkit-design-summary.md +2 -1
  106. package/.bkit/core/prompts/bkit-design-update.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-complexity-check.md +2 -1
  108. package/.bkit/core/prompts/bkit-plan-complexity-split.md +4 -3
  109. package/.bkit/core/prompts/bkit-plan-generate.md +2 -1
  110. package/.bkit/core/prompts/bkit-plan-review-1.md +2 -1
  111. package/.bkit/core/prompts/bkit-plan-review-2.md +2 -1
  112. package/.bkit/core/prompts/bkit-plan-review-3.md +2 -1
  113. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +3 -2
  114. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +3 -2
  115. package/.bkit/core/prompts/bkit-plan-summary.md +2 -1
  116. package/.bkit/core/prompts/bkit-plan-update.md +3 -2
  117. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +2 -1
  118. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +2 -1
  119. package/.bkit/core/prompts/bkit-ship-summary.md +2 -1
  120. package/.bkit/core/prompts/bkit-ship-update-docs.md +2 -1
  121. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +2 -1
  122. package/.bkit/core/prompts/bkit-utility-update-decisions.md +2 -1
  123. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +2 -1
  124. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  125. package/.bkit/core/prompts/bkit-utility-update-failures.md +2 -1
  126. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +2 -1
  127. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -3
  128. package/.bkit/core/workflows/bkit-auto.md +1 -1
  129. package/.bkit/core/workflows/bkit-build.md +35 -21
  130. package/.bkit/core/workflows/bkit-debug.md +31 -22
  131. package/.bkit/core/workflows/bkit-design.md +83 -38
  132. package/.bkit/core/workflows/bkit-plan.md +10 -2
  133. package/.bkit/core/workflows/bkit-ship.md +10 -2
  134. package/.bkit/shared/.agents/plugins/bkit/hooks.json +36 -0
  135. package/.bkit/shared/.agents/plugins/bkit/plugin.json +5 -0
  136. package/.bkit/shared/.claude/settings.json +19 -0
  137. package/.bkit/shared/.codex/hooks.json +21 -0
  138. package/.bkit/shared/.cursor/hooks.json +6 -1
  139. package/.bkit/shared/.opencode/opencode.json +1 -1
  140. package/.bkit/shared/GEMINI.md +11 -0
  141. package/.bkit/shared/docs/deployments.md +1 -1
  142. package/.bkit/shared/docs/security.md +3 -3
  143. package/.bkit/shared/docs/testing.md +12 -1
  144. package/.bkit/templates/.github/dependabot.yml +6 -0
  145. package/.bkit/templates/.github/renovate.json5 +3 -3
  146. package/.bkit/templates/.github/workflows/bkit-ci.yml +24 -13
  147. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  148. package/.bkit/templates/.prettierignore +4 -1
  149. package/.bkit/templates/context/bkit-expo.md +22 -13
  150. package/.bkit/templates/context/bkit-github.md +20 -6
  151. package/.bkit/templates/context/bkit-inngest.md +10 -4
  152. package/.bkit/templates/context/bkit-maestro.md +5 -5
  153. package/.bkit/templates/context/bkit-playwright.md +3 -3
  154. package/.bkit/templates/context/bkit-sentry.md +6 -5
  155. package/.bkit/templates/context/bkit-stripe.md +31 -8
  156. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  157. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  158. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  159. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  160. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +2 -2
  161. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  162. package/.bkit/templates/slop-scan.config.json +10 -3
  163. package/CHANGELOG.md +62 -0
  164. package/LICENSE.md +21 -161
  165. package/README.md +66 -35
  166. package/dist/checks/after/auth.js +28 -0
  167. package/dist/checks/after/github.js +4 -4
  168. package/dist/checks/after/index.js +29 -45
  169. package/dist/checks/after/managed.js +41 -1
  170. package/dist/checks/before/index.js +5 -4
  171. package/dist/checks/before/mcp.js +53 -53
  172. package/dist/checks/status-holes.js +1 -1
  173. package/dist/checks/tips/catalogue.js +297 -0
  174. package/dist/checks/tips/detect.js +130 -0
  175. package/dist/checks/tips/index.js +146 -0
  176. package/dist/cli.js +68 -17
  177. package/dist/commands/install/check.js +2 -0
  178. package/dist/commands/install/doctor.js +9 -1
  179. package/dist/commands/install/install.js +49 -8
  180. package/dist/commands/install/uninstall.js +61 -34
  181. package/dist/commands/install/upgrade.js +31 -33
  182. package/dist/commands/launch.js +27 -11
  183. package/dist/commands/tips.js +10 -0
  184. package/dist/commands/workflow/prs.js +13 -1
  185. package/dist/commands/workflow/runs.js +74 -18
  186. package/dist/commands/workflow/runtime.js +8 -0
  187. package/dist/commands/workflow/steps.js +1 -0
  188. package/dist/commands/workflow/tests.js +541 -4
  189. package/dist/commands/workflow/workstreams.js +4 -4
  190. package/dist/install/cloud-env.js +3 -14
  191. package/dist/install/hosts.js +22 -0
  192. package/dist/install/managed-block.js +36 -0
  193. package/dist/install/manifest.js +79 -4
  194. package/dist/install/modules/antigravity.js +225 -0
  195. package/dist/install/modules/claude.js +6 -6
  196. package/dist/install/modules/cloud.js +2 -2
  197. package/dist/install/modules/codex.js +8 -5
  198. package/dist/install/modules/core.js +21 -6
  199. package/dist/install/modules/cursor.js +6 -6
  200. package/dist/install/modules/index.js +17 -6
  201. package/dist/install/modules/opencode.js +4 -4
  202. package/dist/install/payload-links.js +5 -5
  203. package/dist/install/placeholders.js +1 -1
  204. package/dist/install/version-file.js +12 -3
  205. package/dist/install/write.js +61 -2
  206. package/dist/render/hosts.js +149 -1
  207. package/dist/render/models.js +9 -0
  208. package/dist/shared/package-roots.js +8 -11
  209. package/package.json +8 -8
  210. package/.bkit/core/LICENSE.md +0 -149
  211. package/.bkit/shared/LICENSE.md +0 -22
  212. package/.bkit/templates/LICENSE.md +0 -22
@@ -96,6 +96,8 @@ export interface UninstallResult {
96
96
  deleted: string[];
97
97
  stripped: string[];
98
98
  preserved: string[];
99
+ /** Manifest-listed files already missing on disk (`skip-absent`) — nothing done. */
100
+ absent: string[];
99
101
  decisions: FileSummary[];
100
102
  dryRun: boolean;
101
103
  }
@@ -248,6 +250,7 @@ const CORE_TEMPLATE_DOCTRINE: ManifestEntry[] = [
248
250
  { path: ".agents/context.md", format: "markered-text", module: "core" },
249
251
  { path: ".agents/docs.md", format: "markered-text", module: "core" },
250
252
  { path: ".agents/rules.md", format: "markered-text", module: "core" },
253
+ { path: ".agents/shortcuts.md", format: "markered-text", module: "core" },
251
254
  { path: ".agents/skills.md", format: "markered-text", module: "core" },
252
255
  ];
253
256
 
@@ -283,7 +286,7 @@ export function buildDecisionTable(
283
286
  modules instanceof Set
284
287
  ? ([...modules].filter((m) =>
285
288
  // Includes the opt-in add-ons (cloud) a Set caller passes.
286
- ["core", "claude", "cursor", "opencode", "codex", "cloud"].includes(m),
289
+ ["core", "claude", "cursor", "opencode", "codex", "antigravity", "cloud"].includes(m),
287
290
  ) as ModuleName[])
288
291
  : (modules as ModuleName[]);
289
292
 
@@ -493,6 +496,7 @@ export async function runUninstall(
493
496
  deleted: [],
494
497
  stripped: [],
495
498
  preserved: [],
499
+ absent: [],
496
500
  decisions: [],
497
501
  dryRun: ctx.dryRun,
498
502
  };
@@ -501,7 +505,7 @@ export async function runUninstall(
501
505
  modules instanceof Set
502
506
  ? ([...modules].filter((m) =>
503
507
  // Includes the opt-in add-ons (cloud) a Set caller passes.
504
- ["core", "claude", "cursor", "opencode", "codex", "cloud"].includes(m),
508
+ ["core", "claude", "cursor", "opencode", "codex", "antigravity", "cloud"].includes(m),
505
509
  ) as ModuleName[])
506
510
  : (modules as ModuleName[]);
507
511
 
@@ -531,7 +535,14 @@ export async function runUninstall(
531
535
  const absPath = path.join(ctx.cwd, summary.file);
532
536
 
533
537
  switch (summary.decision) {
534
- case "skip-absent":
538
+ case "skip-absent": {
539
+ result.absent.push(summary.file);
540
+ if (!ctx.dryRun) {
541
+ console.log(`${ctx.logPrefix} absent: ${summary.file} (${summary.reason})`);
542
+ }
543
+ break;
544
+ }
545
+
535
546
  case "skip-modified":
536
547
  case "skip-unknown":
537
548
  case "preserve": {
@@ -701,7 +712,8 @@ export async function runUninstall(
701
712
 
702
713
  // Clean up .agents/ bkit-prefix mirror files
703
714
  // (.claude/commands/bkit-*.md, .claude/agents/bkit-*.md, .opencode/agents/bkit-*.md, etc.)
704
- if (!ctx.dryRun) {
715
+ // A dry run lists the same paths in result.deleted and removes nothing.
716
+ {
705
717
  const mirrorDirs = [
706
718
  // Each host's mirror dirs are gated on its own module so a targeted
707
719
  // uninstall (e.g. --claude / --auto) leaves other hosts
@@ -715,6 +727,9 @@ export async function runUninstall(
715
727
  // separately below: `.agents/skills/` is SHARED with third-party skills installed via
716
728
  // skills.sh, so the directory itself must never be removed wholesale.
717
729
  ...(moduleList.includes("codex") ? [".codex/agents"] : []),
730
+ // antigravity plugin subagent mirrors (`.agents/plugins/bkit/agents/bkit-*.md`). The
731
+ // plugin's workflow skills (`.agents/plugins/bkit/skills/bkit-*`) are swept below.
732
+ ...(moduleList.includes("antigravity") ? [".agents/plugins/bkit/agents"] : []),
718
733
  ];
719
734
  for (const dir of mirrorDirs) {
720
735
  const absDir = path.join(ctx.cwd, dir);
@@ -724,33 +739,42 @@ export async function runUninstall(
724
739
  // .toml as well as .md: codex agent mirrors are TOML.
725
740
  if (!f.startsWith("bkit-") || !(f.endsWith(".md") || f.endsWith(".toml"))) continue;
726
741
  const absFile = path.join(absDir, f);
727
- fs.rmSync(absFile, { force: true });
742
+ if (!ctx.dryRun) fs.rmSync(absFile, { force: true });
728
743
  result.deleted.push(path.join(dir, f));
729
- console.log(`${ctx.logPrefix} delete mirror: ${path.join(dir, f)}`);
744
+ if (!ctx.dryRun) console.log(`${ctx.logPrefix} delete mirror: ${path.join(dir, f)}`);
730
745
  }
731
746
  } catch (err) {
732
747
  console.error(`${ctx.logPrefix} error cleaning up ${dir}: ${(err as Error).message}`);
733
748
  }
734
749
  }
735
750
 
736
- // Workflow skills: `.agents/skills/` is SHARED with third-party skills installed via
737
- // skills.sh, so only the bkit-prefixed DIRECTORIES are removed — never the parent.
738
- if (moduleList.includes("codex")) {
739
- const skillsDir = path.join(ctx.cwd, ".agents", "skills");
740
- if (fs.existsSync(skillsDir)) {
741
- try {
742
- for (const d of fs.readdirSync(skillsDir)) {
743
- if (!d.startsWith("bkit-")) continue;
744
- const abs = path.join(skillsDir, d);
745
- if (!fs.statSync(abs).isDirectory()) continue;
746
- fs.rmSync(abs, { recursive: true, force: true });
747
- result.deleted.push(path.join(".agents/skills", d));
748
- console.log(`${ctx.logPrefix} delete mirror: ${path.join(".agents/skills", d)}`);
751
+ // Workflow skills. Codex's live at `.agents/skills/` (SHARED with third-party skills
752
+ // installed via skills.sh, so only the bkit-prefixed DIRECTORIES are removed — never the
753
+ // parent); Antigravity's live in its plugin at `.agents/plugins/bkit/skills/`. Sweep each
754
+ // host's set independently.
755
+ const skillDirs = [
756
+ ...(moduleList.includes("codex") ? [path.join(".agents", "skills")] : []),
757
+ ...(moduleList.includes("antigravity")
758
+ ? [path.join(".agents", "plugins", "bkit", "skills")]
759
+ : []),
760
+ ];
761
+ for (const skillsDir of skillDirs) {
762
+ const absDir = path.join(ctx.cwd, skillsDir);
763
+ if (!fs.existsSync(absDir)) continue;
764
+ try {
765
+ for (const d of fs.readdirSync(absDir)) {
766
+ if (!d.startsWith("bkit-")) continue;
767
+ const abs = path.join(absDir, d);
768
+ if (!fs.statSync(abs).isDirectory()) continue;
769
+ if (!ctx.dryRun) fs.rmSync(abs, { recursive: true, force: true });
770
+ result.deleted.push(path.join(skillsDir, d));
771
+ if (!ctx.dryRun) {
772
+ console.log(`${ctx.logPrefix} delete mirror: ${path.join(skillsDir, d)}`);
749
773
  }
750
- } catch (err) {
751
- const msg = (err as Error).message;
752
- console.error(`${ctx.logPrefix} error cleaning up .agents/skills: ${msg}`);
753
774
  }
775
+ } catch (err) {
776
+ const msg = (err as Error).message;
777
+ console.error(`${ctx.logPrefix} error cleaning up ${skillsDir}: ${msg}`);
754
778
  }
755
779
  }
756
780
  }
@@ -865,6 +889,7 @@ export async function runUninstall(
865
889
  ctx.cwd,
866
890
  existing.canonicalHashes,
867
891
  {},
892
+ result.deleted,
868
893
  );
869
894
  if (pruned > 0) {
870
895
  console.log(
@@ -1012,16 +1037,16 @@ export async function runUninstallCommand(
1012
1037
  const moduleList = [...modules] as ModuleName[];
1013
1038
  console.log(`${LOG_PREFIX} Running uninstall${uninstallCtx.dryRun ? " (dry-run)" : ""}...`);
1014
1039
  const result = await runUninstall(moduleList, uninstallCtx);
1015
- const totalDeleted = result.deleted.length;
1016
- const totalStripped = result.stripped.length;
1017
- const totalPreserved = result.preserved.length;
1018
- if (uninstallCtx.dryRun) {
1019
- console.log(
1020
- `${LOG_PREFIX} [dry-run] Would delete: ${totalDeleted}, strip: ${totalStripped}, preserve: ${totalPreserved}`,
1021
- );
1022
- } else {
1023
- console.log(
1024
- `${LOG_PREFIX} Done. Deleted: ${totalDeleted}, stripped: ${totalStripped}, preserved: ${totalPreserved}`,
1025
- );
1026
- }
1040
+ console.log(uninstallSummaryLine(result, LOG_PREFIX));
1041
+ }
1042
+
1043
+ /** The closing totals line of an uninstall run (dry-run wording when `result.dryRun`). */
1044
+ export function uninstallSummaryLine(result: UninstallResult, logPrefix: string): string {
1045
+ const deleted = result.deleted.length;
1046
+ const stripped = result.stripped.length;
1047
+ const preserved = result.preserved.length;
1048
+ const absent = result.absent.length;
1049
+ return result.dryRun
1050
+ ? `${logPrefix} [dry-run] Would delete: ${deleted}, strip: ${stripped}, preserve: ${preserved}, already absent: ${absent}`
1051
+ : `${logPrefix} Done. Deleted: ${deleted}, stripped: ${stripped}, preserved: ${preserved}, already absent: ${absent}`;
1027
1052
  }
@@ -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 {
@@ -77,6 +78,7 @@ import {
77
78
  parseModelLookup,
78
79
  applyModelOverrides,
79
80
  buildOpencodeModelLookup,
81
+ buildAntigravityModelLookup,
80
82
  parseEffortMap,
81
83
  } from "../../render/models.js";
82
84
 
@@ -478,8 +480,8 @@ export function updateCanonicalHashesAfterUpgrade(
478
480
 
479
481
  const fresh: Record<string, string> = {};
480
482
  for (const relPath of seedablePaths) {
481
- // Exclude .agents/ internal files (docs.md, friction.md, rules.md, skills.md,
482
- // .env.example etc.) from canonicalHashes — they are not consumer-facing files
483
+ // Exclude .agents/ internal files (docs.md, friction.md, rules.md, shortcuts.md,
484
+ // skills.md, .env.example etc.) from canonicalHashes — they are not consumer-facing files
483
485
  // whose hashes bkit uses for drift detection. Mirrors the same filter applied
484
486
  // in the install path (install/modules/index.ts postDispatch). Template copies carry no
485
487
  // hash there either.
@@ -527,20 +529,6 @@ export function updateCanonicalHashesAfterUpgrade(
527
529
  writeBkitVersion(versionFile, updated);
528
530
  }
529
531
 
530
- /**
531
- * Detect which host modules a consumer has installed, by the presence of each host's
532
- * source-rendered agents directory. Used by `bkit upgrade` to re-render only the hosts
533
- * the consumer installed — never force-creating an opencode/cursor tree.
534
- */
535
- export function detectInstalledHostModules(cwd: string): Set<ModuleFlag> {
536
- const mods = new Set<ModuleFlag>();
537
- if (fs.existsSync(path.join(cwd, ".claude", "agents"))) mods.add("claude");
538
- if (fs.existsSync(path.join(cwd, ".cursor", "agents"))) mods.add("cursor");
539
- if (fs.existsSync(path.join(cwd, ".opencode", "agents"))) mods.add("opencode");
540
- if (fs.existsSync(path.join(cwd, ".codex", "agents"))) mods.add("codex");
541
- return mods;
542
- }
543
-
544
532
  /**
545
533
  * Resolve the newest published @cbartens/bkit version from the registry for
546
534
  * `bkit upgrade --latest`. Shells out to `pnpm view` (honours the consumer's
@@ -733,8 +721,6 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
733
721
  if (ent.isDirectory()) {
734
722
  collectPayload(entAbs, entRel, skipTopDirs);
735
723
  } else if (ent.isFile()) {
736
- // Each payload root's LICENSE.md is package metadata, never an install source.
737
- if (ent.name === "LICENSE.md") continue;
738
724
  // Single shared dotfile remap (gitignore → .gitignore, npmignore → .npmignore).
739
725
  const relPath = remapTemplateDest(entRel);
740
726
  // `.claude/bkit-cloud.md` + `.cursor/bkit-cloud.md` are GENERATED output files
@@ -745,15 +731,22 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
745
731
  // (host-gated, non-dry-run).
746
732
  if (relPath === CLAUDE_CLOUD_RELPATH || relPath === CURSOR_CLOUD_RELPATH) continue;
747
733
  if (relPath === MCP_ROOT_RELPATH || relPath === CURSOR_MCP_RELPATH) continue;
748
- // 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.
749
741
  if (optInPaths.has(relPath) && !fs.existsSync(path.join(process.cwd(), relPath))) {
750
- continue;
742
+ const hostInstalled = ownerModule !== undefined && installedModules.has(ownerModule);
743
+ if (!hostInstalled || (relPath === OPENCODE_JSON_RELPATH && !upgradeOpencodeProvider)) {
744
+ continue;
745
+ }
751
746
  }
752
- const entry = entryByPath.get(relPath);
753
747
  // Skip host-module files when that module is not installed — upgrade updates
754
748
  // only what the consumer opted into, never force-creating a new module. opt-ins are
755
- // handled by the dest-presence check above; core + entry-less files always pass.
756
- const ownerModule = entry?.module;
749
+ // handled by the check above; core + entry-less files always pass.
757
750
  if (
758
751
  ownerModule &&
759
752
  ownerModule !== "core" &&
@@ -802,11 +795,8 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
802
795
 
803
796
  // Payload view links — the same sync install runs (`.bkit/core` + `.bkit/shared`
804
797
  // point into the installed package). Never clobbers a real directory; a platform
805
- // refusal is reported, never fatal. Throwaway WriteSet: links carry no hash.
806
- const linkChanges = syncPayloadLinks(process.cwd(), {
807
- dryRun: upgradeFlags.dryRun,
808
- ws: { writes: [] },
809
- });
798
+ // refusal is reported, never fatal. Links carry no hash.
799
+ const linkChanges = syncPayloadLinks(process.cwd(), { dryRun: upgradeFlags.dryRun });
810
800
  const linkReport = formatPayloadLinkChanges(linkChanges);
811
801
  if (linkReport) console.log(`${LOG_PREFIX} ${linkReport}`);
812
802
 
@@ -855,6 +845,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
855
845
  let renderModelLookup: Map<string, string> = new Map();
856
846
  let renderOpencodeModelLookup: Map<string, string> = new Map();
857
847
  let renderCodexModelLookup: Map<string, string> = new Map();
848
+ let renderAntigravityModelLookup: Map<string, string> = new Map();
858
849
  let renderEffortMap: EffortMap = new Map();
859
850
  const pkgPromptsMd = path.join(getBkitDocsRoot(), "prompts.md");
860
851
  const consumerPromptsMd = path.join(process.cwd(), ".bkit", "prompts.md");
@@ -882,6 +873,14 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
882
873
  }
883
874
  applyModelOverrides(renderCodexModelLookup, "openai", consumerPromptsMd);
884
875
  }
876
+ if (renderModules.has("antigravity")) {
877
+ try {
878
+ renderAntigravityModelLookup = buildAntigravityModelLookup(pkgPromptsMd);
879
+ } catch {
880
+ // Not fatal — the antigravity module fails per-file if a model is missing
881
+ }
882
+ applyModelOverrides(renderAntigravityModelLookup, "google", consumerPromptsMd);
883
+ }
885
884
  renderEffortMap = parseEffortMap(pkgPromptsMd);
886
885
  }
887
886
  const renderWs: WriteSet = { writes: [] };
@@ -891,6 +890,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
891
890
  modelLookup: renderModelLookup,
892
891
  opencodeModelLookup: renderOpencodeModelLookup,
893
892
  codexModelLookup: renderCodexModelLookup,
893
+ antigravityModelLookup: renderAntigravityModelLookup,
894
894
  effortMap: renderEffortMap,
895
895
  opencodeProvider: renderProvider,
896
896
  advisories: [],
@@ -902,6 +902,8 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
902
902
  // Re-stamp every rendered agent + command at the version we are upgrading TO,
903
903
  // so a clean upgrade refreshes the managed-version marker and `bkit check` stays green.
904
904
  version: getInstallingVersion(),
905
+ // The detected host set — read by the Antigravity module for the Codex-overlap advisory.
906
+ installedModules: renderModules,
905
907
  };
906
908
  const rendered = renderManagedOutputs(renderModules, renderCtx);
907
909
 
@@ -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
+ }
@@ -56,6 +56,14 @@ export type Probe =
56
56
  | { kind: "unavailable"; message: string }
57
57
  | { kind: "failed"; message: string };
58
58
 
59
+ /**
60
+ * The `owner/repo` a PR URL points at, or undefined when it is not a recognizable
61
+ * GitHub PR URL. Lets a caller compare the repo a PR resolved in against `--repo`.
62
+ */
63
+ export function prRepoSlug(url: string | null | undefined): string | undefined {
64
+ return /^https?:\/\/[^/]+\/([^/]+\/[^/]+)\/pull\//.exec(url ?? "")?.[1];
65
+ }
66
+
59
67
  function ghFailure(res: GhResult, what: string): Probe {
60
68
  const detail = res.stderr.split("\n").at(-1) || `exit ${String(res.status)}`;
61
69
  return ghUnavailable(res)
@@ -70,10 +78,19 @@ function ghFailure(res: GhResult, what: string): Probe {
70
78
  */
71
79
  export function probePr(
72
80
  cwd: string,
73
- opts: { head?: string; base?: string; state: "open" | "all"; number?: string },
81
+ opts: {
82
+ head?: string;
83
+ base?: string;
84
+ state: "open" | "all";
85
+ number?: string;
86
+ /** Honour `--repo`: resolve the PR in this owner/repo, not the checkout's remote. */
87
+ repo?: string;
88
+ },
74
89
  ): Probe {
75
90
  if (opts.number !== undefined) {
76
- const res = runGh(cwd, ["pr", "view", opts.number, "--json", `${PR_FIELDS},mergeable`]);
91
+ const args = ["pr", "view", opts.number, "--json", `${PR_FIELDS},mergeable`];
92
+ if (opts.repo !== undefined) args.push("--repo", opts.repo);
93
+ const res = runGh(cwd, args);
77
94
  if (!res.ok) return ghFailure(res, `gh pr view ${opts.number}`);
78
95
  const parsed = parseJson(res.stdout);
79
96
  if (!parsed.ok) return { kind: "failed", message: "gh pr view printed no JSON" };
@@ -81,6 +98,7 @@ export function probePr(
81
98
  }
82
99
  const args = ["pr", "list", "--head", opts.head!, "--state", opts.state, "--json", PR_FIELDS];
83
100
  if (opts.base !== undefined) args.push("--base", opts.base);
101
+ if (opts.repo !== undefined) args.push("--repo", opts.repo);
84
102
  const res = runGh(cwd, args);
85
103
  if (!res.ok) return ghFailure(res, `gh pr list --head ${opts.head!}`);
86
104
  const parsed = parseJson(res.stdout);
@@ -45,7 +45,7 @@ import { TIMEOUTS } from "../../shared/timeouts.js";
45
45
  import { FID_PATTERNS, fromBranch, fromMarker, issueIdOf, readIssueTracker } from "./fids.js";
46
46
  import { AUTO_LABEL, AUTO_ROUTE_SUFFIX } from "./issues.js";
47
47
  import { checkOnlyBookkeeping } from "./ledgers.js";
48
- import { closeTransportRow, crossCheckFile, probePr } from "./prs.js";
48
+ import { closeTransportRow, crossCheckFile, prRepoSlug, probePr, type PrInfo } from "./prs.js";
49
49
  import { resolveOwnerRepo, splitSlug } from "./repo.js";
50
50
  import { extraField, str } from "./status.js";
51
51
  import { writeStepRow } from "./steps.js";
@@ -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
  });
@@ -1357,6 +1373,27 @@ function auditRow(file: string, type: string, fields: Record<string, unknown>):
1357
1373
  );
1358
1374
  }
1359
1375
 
1376
+ /**
1377
+ * Log where a `--pr` resolved so a `--repo` naming a repo other than the checkout
1378
+ * is visible; the PR URL names the repo `gh` actually read from.
1379
+ */
1380
+ function logResolvedPrRepo(
1381
+ repoFlag: string | undefined,
1382
+ prNumber: string,
1383
+ pr: PrInfo | undefined,
1384
+ log: (m: string) => void,
1385
+ ): void {
1386
+ if (repoFlag === undefined) return;
1387
+ const resolved = prRepoSlug(pr?.url);
1388
+ if (resolved === undefined) {
1389
+ log(`PR ${prNumber}: could not read the resolved repo from its URL (--repo ${repoFlag})`);
1390
+ } else if (resolved !== repoFlag) {
1391
+ log(`PR ${prNumber} resolved in ${resolved} — --repo names ${repoFlag}`);
1392
+ } else {
1393
+ log(`PR ${prNumber} resolved in ${repoFlag}`);
1394
+ }
1395
+ }
1396
+
1360
1397
  function runGate(ctx: RunContext): number {
1361
1398
  const f = ctx.flags;
1362
1399
  const given = [f.head, f.pr, f.squashOf].filter((v) => v !== undefined).length;
@@ -1374,12 +1411,13 @@ function runGate(ctx: RunContext): number {
1374
1411
  if (prNumber !== undefined) {
1375
1412
  if (!/^[1-9][0-9]*$/.test(prNumber))
1376
1413
  throw new CommandError(EXIT.USAGE, "--pr / --squash-of take a PR number");
1377
- pr = probePr(ctx.cwd, { number: prNumber, state: "open" });
1414
+ pr = probePr(ctx.cwd, { number: prNumber, state: "open", repo: str(f.repo) });
1378
1415
  if (pr.kind === "unavailable") {
1379
1416
  ctx.log(pr.message);
1380
1417
  return EXIT.USE_MCP;
1381
1418
  }
1382
1419
  const info = pr.kind === "ok" ? pr.pr : undefined;
1420
+ logResolvedPrRepo(str(f.repo), prNumber, info, ctx.log);
1383
1421
  head = (f.squashOf !== undefined ? info?.mergeCommit?.oid : info?.headRefOid) ?? "";
1384
1422
  if (head === "") {
1385
1423
  ctx.log(
@@ -1401,10 +1439,25 @@ function runGate(ctx: RunContext): number {
1401
1439
  const snapshot = str(f.snapshot);
1402
1440
  if (snapshot !== undefined) {
1403
1441
  const info = pr?.kind === "ok" ? pr.pr : undefined;
1404
- const dev = git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "";
1405
- 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
+ }
1406
1456
  const ciWorkflow = readBkitConfig(root).ciWorkflow;
1407
- const runs = gh([
1457
+ const runs = repoScopedGh(
1458
+ gh,
1459
+ repoFlag,
1460
+ )([
1408
1461
  "run",
1409
1462
  "list",
1410
1463
  "--branch",
@@ -1506,7 +1559,9 @@ function devRequiresChecks(gh: Gh, repo: string): boolean {
1506
1559
 
1507
1560
  async function runRevalidate(ctx: RunContext): Promise<number> {
1508
1561
  const f = ctx.flags;
1509
- const d = deps(ctx);
1562
+ const repoFlag = str(f.repo);
1563
+ const d = deps(ctx, repoFlag);
1564
+ const foreign = isForeignRepo(ctx.cwd, repoFlag);
1510
1565
  const branch = String(f.branch);
1511
1566
  const entry = String(f.entryHead);
1512
1567
  const codeHead = String(f.codeHead);
@@ -1514,12 +1569,13 @@ async function runRevalidate(ctx: RunContext): Promise<number> {
1514
1569
  if (!["head-move", "gate-refusal"].includes(reason))
1515
1570
  throw new CommandError(EXIT.USAGE, "--reason must be head-move or gate-refusal");
1516
1571
  const status = path.resolve(ctx.cwd, String(f.file));
1517
- runGit(ctx.cwd, ["fetch", "origin", branch]);
1518
- const pr = probePr(ctx.cwd, { number: String(f.pr), state: "open" });
1572
+ if (!foreign) runGit(ctx.cwd, ["fetch", "origin", branch]);
1573
+ const pr = probePr(ctx.cwd, { number: String(f.pr), state: "open", repo: repoFlag });
1519
1574
  if (pr.kind === "unavailable") {
1520
1575
  ctx.log(pr.message);
1521
1576
  return EXIT.USE_MCP;
1522
1577
  }
1578
+ logResolvedPrRepo(str(f.repo), String(f.pr), pr.kind === "ok" ? pr.pr : undefined, ctx.log);
1523
1579
  const current = pr.kind === "ok" ? (pr.pr?.headRefOid ?? "") : "";
1524
1580
  if (current === "") {
1525
1581
  ctx.log("cannot read the PR head — query failed (403 = PAT scope)");
@@ -1529,14 +1585,22 @@ async function runRevalidate(ctx: RunContext): Promise<number> {
1529
1585
  // CI must pass at the code head while the PR head adds bookkeeping only and dev
1530
1586
  // demands no status checks; otherwise at the PR head.
1531
1587
  let validated = codeHead;
1532
- const book = onlyBookkeeping(checkoutRoot(ctx.cwd), {
1533
- month: String(f.month),
1534
- fid: String(f.fid),
1535
- from: codeHead,
1536
- to: current,
1537
- });
1538
- if (!book.ok) validated = current;
1539
- 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;
1540
1604
  if (repo !== undefined && devRequiresChecks(d.gh, repo)) {
1541
1605
  ctx.log(`dev requires status checks — validating at the PR head ${current}`);
1542
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,