karajan-code 4.43.0 → 4.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.43.0",
+  "version": "4.44.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli/register-meta.js

@@ -169,6 +169,16 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0986 (HUM-F): the invitation to enroll the phone, once per version.
+  identityCmd
+    .command("phone-invite")
+    .description("Print, once per kj version, the invitation to enroll the phone when none is enrolled (nothing otherwise)")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "identity-phone-invite", flags, async ({ config }) => {
+        process.exitCode = await identityCommand({ action: "phone-invite", config, flags: { ...flags, version: pkgVersion } });
+      });
+    });
+
   // BOOT-A (KJC-TSK-0857, cold-start ADR): the pieces existed, the ORDER did
   // not. One command from an empty directory to a project under the method.
   program

package/src/commands/doctor.js

@@ -21,6 +21,7 @@ import { getBinaryChecks } from "../checks/binaries.js";
 import { getSonarChecks } from "../checks/sonar.js";
 import { getOllamaChecks } from "../checks/ollama.js";
 import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
+import { getPhoneChecks } from "../harden/phone-invite.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
 import { getSqueezrChecks } from "../checks/squeezr.js";
@@ -67,6 +68,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSonarChecks(),
     ...getOllamaChecks(),
     ...getHarnessScorecardChecks(),
+    ...getPhoneChecks(),
     ...getPortChecks(),
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),

package/src/commands/identity.js

@@ -9,6 +9,7 @@
  */
 
 import { addSigner, enrollPhone } from "../harden/phone-sign.js";
+import { phoneInvite } from "../harden/phone-invite.js";
 import { readIdentity, writeIdentity } from "../identity/store.js";
 import { activeGhUser, effectiveGitEmail } from "../identity/detect.js";
 import { compareIdentity } from "../identity/compare.js";
@@ -39,6 +40,14 @@ export async function identityCommand({ action = "show", config, flags = {}, dep
     return 0;
   }
 
+  // KJC-TSK-0986 (HUM-F): the once-per-version invitation to enroll the phone,
+  // printed for the SessionStart hook (which cannot import kj) and for scripts.
+  if (action === "phone-invite") {
+    const text = phoneInvite({ home: deps.home, version: flags.version });
+    if (text) log(text);
+    return 0;
+  }
+
   if (action === "set") {
     const candidate = { gh_user: flags.gh || effective.gh_user, git_email: flags.email || effective.git_email };
     if (!candidate.gh_user || !candidate.git_email) {

package/src/git/automation.js

@@ -6,6 +6,9 @@
 import { addCheckpoint } from "../session/store.js";
 import { pipelineSonarBlock, stampStagedVerdict } from "../review/verdict-store.js";
 import { branchSize } from "../commands/pr-size.js";
+import { pushRemedy } from "./hu-automation.js";
+import { resolveRunIdentity } from "./run-identity.js";
+import { getRunContext } from "../utils/run-context.js";
 import {
   ensureGitRepo,
   currentBranch,
@@ -14,6 +17,7 @@ import {
   syncBaseBranch,
   ensureBranchUpToDateWithBase,
   createBranch,
+  checkoutBranch,
   buildBranchName,
   commitAll,
   pushBranch,
@@ -104,6 +108,17 @@ export function buildFinalizeCommitMessage({ task, taskType, pendingPaths }) {
   return commitMessageFromTask(task, taskType);
 }
 
+// KJC-BUG-0249 (#1896): a branch named after the card is the same on a second
+// run of that card, so one already there is taken, not recreated.
+async function checkoutRunBranch(created) {
+  try {
+    await createBranch(created);
+  } catch (err) {
+    if (!/already exists/i.test(err.message)) throw err;
+    await checkoutBranch(created);
+  }
+}
+
 export async function prepareGitAutomation({ config, task, logger, session }) {
   const enabled = config.git.auto_commit || config.git.auto_push || config.git.auto_pr;
   if (!enabled) return { enabled: false };
@@ -112,6 +127,20 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
     throw new Error("Git automation requested but current directory is not a git repository");
   }
 
+  // KJC-BUG-0246 (#1893): one identity for every commit of the run, resolved
+  // once: the clone's declaration, else the repository's config, else the
+  // global one. From the global config it is said, because another session
+  // may switch it mid-run. Nothing resolvable: git refuses the commit loudly.
+  const identity = resolveRunIdentity({ projectDir: config.projectDir || process.cwd() });
+  const runContext = getRunContext();
+  if (identity && runContext) runContext.gitIdentity = identity;
+  if (identity) {
+    logger.info(`Git identity for this run: ${identity.name} <${identity.email}> (${identity.source})`);
+    if (identity.source === "global") logger.warn("The identity comes from the global git config, which another session may switch mid-run: declare this clone's with kj identity set, or set user.email in this repository");
+  } else {
+    logger.warn("No git identity resolvable (kj identity set, or git config user.name and user.email): the first commit will fail");
+  }
+
   const baseBranch = config.base_branch;
   const autoRebase = config.git.auto_rebase !== false;
   // KJC-BUG-0294 (#1993): what is dirty or untracked NOW is not the run's; the
@@ -123,7 +152,7 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
 
   // New repo without commits: create branch directly (no fetch/sync possible)
   if (!repoHasCommits) {
-    const created = buildBranchName(config.git.branch_prefix || "feat/", task);
+    const created = buildBranchName(config.git.branch_prefix || "feat/", task, session?.pg_task_id || null);
     // git checkout -b works even without commits (creates orphan-like branch on first commit)
     await createBranch(created);
     logger.info(`New repo — created working branch: ${created}`);
@@ -148,8 +177,8 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
     await syncBaseBranch({ baseBranch, autoRebase }).catch(() => {
       // No remote tracking — skip sync for new projects
     });
-    const created = buildBranchName(config.git.branch_prefix || "feat/", task);
-    await createBranch(created);
+    const created = buildBranchName(config.git.branch_prefix || "feat/", task, session?.pg_task_id || null);
+    await checkoutRunBranch(created);
     branch = created;
     logger.info(`Created working branch: ${branch}`);
     await addCheckpoint(session, { stage: "git-prep", branch, created: true });
@@ -353,7 +382,12 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
   }
 
   if (remoteAvailable && (config.git.auto_push || config.git.auto_pr)) {
-    await pushBranch(gitCtx.branch);
+    // KJC-BUG-0248 (#1895): a refused push stops the run loudly, with its remedy.
+    try {
+      await pushBranch(gitCtx.branch);
+    } catch (err) {
+      throw new Error(`push of ${gitCtx.branch} failed: ${err.message}. ${pushRemedy(err.message, gitCtx.branch)}`, { cause: err });
+    }
     await addCheckpoint(session, { stage: "git-push", branch: gitCtx.branch });
     logger.info(`Pushed branch: ${gitCtx.branch}`);
   }

package/src/git/hu-automation.js

@@ -69,6 +69,33 @@ async function resolveExistingBranchRef(preferred) {
   return preferred; // give up; caller will surface the original error
 }
 
+/** Whether a branch name references the card, as a whole token (BB-002 is not BB-0022). */
+export function branchReferencesCard(branch, cardId) {
+  const id = String(cardId).replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+  return new RegExp(`(^|[^a-z0-9])${id}([^a-z0-9]|$)`, "i").test(String(branch || ""));
+}
+
+async function cardBranch({ cardId, story, config, logger }) {
+  const head = await runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], {});
+  const current = head.exitCode === 0 ? head.stdout.trim() : "";
+  if (branchReferencesCard(current, cardId)) {
+    logger.info(`HU ${story.id}: on '${current}', the branch of card ${cardId}`);
+    return current;
+  }
+  const branchName = buildHuBranchName(config.git?.branch_prefix || "feat/", { id: cardId, title: story.title });
+  // A card branch left by an earlier run keeps its commits: taken, never reset.
+  const exists = await runCommand("git", ["rev-parse", "--verify", "--quiet", branchName], {});
+  const base = exists.exitCode === 0 ? null : await resolveExistingBranchRef(config.base_branch || "main");
+  const how = base ? `created from '${base}'` : "taken";
+  const res = await runCommand("git", base ? ["checkout", "-b", branchName, base] : ["checkout", branchName], {});
+  if (res.exitCode !== 0) {
+    logger.warn(`HU git: branch ${branchName} could not be ${how}: ${res.stderr}`);
+    return null;
+  }
+  logger.info(`HU ${story.id}: branch '${branchName}' ${how} for card ${cardId}`);
+  return branchName;
+}
+
 /**
  * Create a branch for an HU starting from its resolved base.
  * Returns the branch name created (or null if git automation is disabled).
@@ -80,10 +107,22 @@ async function resolveExistingBranchRef(preferred) {
  * @param {object} params.logger
  * @returns {Promise<string|null>}
  */
-export async function prepareHuBranch({ story, huBranches, config, logger }) {
+export async function prepareHuBranch({ story, huBranches, config, logger, cardId = null }) {
   if (!config.git?.auto_commit && !config.git?.auto_push && !config.git?.auto_pr) {
     return null;
   }
+  // KJC-BUG-0249 (#1896): with a Planning Game card the run is that card's
+  // work and lives on ONE branch named after it: the current one when it
+  // already references the card, else feat/<CARD-ID>-<slug>, created once
+  // and shared by every HU. HU ids name branches only when there is no card.
+  if (cardId) {
+    const known = huBranches.get(cardId);
+    const branch = known ?? (await cardBranch({ cardId, story, config, logger }));
+    if (!branch) return null;
+    huBranches.set(cardId, branch);
+    huBranches.set(story.id, branch);
+    return branch;
+  }
   const baseBranch = resolveHuBase(story, huBranches, config.base_branch || "main");
   const effectiveBase = await resolveExistingBranchRef(baseBranch);
   if (effectiveBase !== baseBranch) {
@@ -103,18 +142,37 @@ export async function prepareHuBranch({ story, huBranches, config, logger }) {
   return branchName;
 }
 
+/**
+ * KJC-BUG-0248 (#1895): the remedy for a push git refused, read from its
+ * message. GitHub refuses a push that adds or changes a workflow file when
+ * the token lacks the `workflow` scope; that one has an exact fix.
+ */
+export function pushRemedy(message, branch) {
+  if (/workflow/i.test(message) && /scope/i.test(message)) {
+    return `the token lacks the workflow scope: run gh auth refresh -h github.com -s workflow, then git push -u origin ${branch}`;
+  }
+  return `push the branch yourself: git push -u origin ${branch}`;
+}
+
+/** The warnings a run reports when the push or the PR of any HU failed. */
+export function collectGitWarnings(results) {
+  return results.flatMap((r) => (r.result?.git?.errors ?? []).map((e) => `${r.huId}: ${e.step} failed: ${e.message}. ${e.remedy}`));
+}
+
 /**
  * After an HU is approved, commit its changes and optionally push + create PR.
+ * A push or PR that fails is not only a warn line: it travels in `errors`
+ * with its remedy, so the run's result says it (KJC-BUG-0248).
  *
  * @param {object} params
  * @param {object} params.story
  * @param {string} params.branchName
  * @param {object} params.config
  * @param {object} params.logger
- * @returns {Promise<{committed: boolean, pushed: boolean, prUrl: string|null}>}
+ * @returns {Promise<{committed: boolean, pushed: boolean, prUrl: string|null, branch: string|null, errors: Array<{step: string, message: string, remedy: string}>}>}
  */
 export async function finalizeHuCommit({ story, branchName, config, logger, cwd = null }) {
-  const result = { committed: false, pushed: false, prUrl: null };
+  const result = { committed: false, pushed: false, prUrl: null, branch: branchName || null, errors: [] };
   if (!branchName) return result;
 
   const changed = await hasChanges(cwd);
@@ -139,7 +197,9 @@ export async function finalizeHuCommit({ story, branchName, config, logger, cwd
       result.pushed = true;
       logger.info(`HU ${story.id}: pushed '${branchName}'`);
     } catch (err) {
-      logger.warn(`HU ${story.id}: push failed: ${err.message}`);
+      const remedy = pushRemedy(err.message, branchName);
+      result.errors.push({ step: "push", message: err.message, remedy });
+      logger.warn(`HU ${story.id}: push failed: ${err.message} (${remedy})`);
     }
   }
 
@@ -163,7 +223,9 @@ export async function finalizeHuCommit({ story, branchName, config, logger, cwd
       result.prUrl = url;
       logger.info(`HU ${story.id}: PR created ${url}`);
     } catch (err) {
-      logger.warn(`HU ${story.id}: PR creation failed: ${err.message}`);
+      const remedy = `open the PR yourself: gh pr create --base ${config.base_branch || "main"} --head ${branchName}`;
+      result.errors.push({ step: "pr", message: err.message, remedy });
+      logger.warn(`HU ${story.id}: PR creation failed: ${err.message} (${remedy})`);
     }
   }
 

package/src/git/run-identity.js

@@ -0,0 +1,48 @@
+/**
+ * KJC-BUG-0246 (#1893): one git identity for the whole run.
+ *
+ * Of five commits of one run, three carried one account and two another: the
+ * pipeline let git resolve the author at every commit, and the host works with
+ * several global identities that other sessions switch at will. The identity
+ * is resolved ONCE, before the first commit, in a fixed order: the clone's
+ * declaration (`kj identity set`, .karajan/identity.local.yml), else the
+ * repository's own config, else the global one. Nothing resolvable is null,
+ * never a guess: git itself refuses the commit loudly in that case.
+ */
+import { execFileSync } from "node:child_process";
+import { readIdentity } from "../identity/store.js";
+
+const defaultGitFn = (projectDir, args) =>
+  execFileSync("git", ["config", ...args], { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+const configValue = (gitFn, projectDir, args) => {
+  try {
+    const out = String(gitFn(projectDir, args) || "").trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * @param {{projectDir: string, gitFn?: (projectDir: string, args: string[]) => string}} opts
+ * @returns {{name: string, email: string, source: "declared"|"repo"|"global"}|null}
+ */
+export function resolveRunIdentity({ projectDir, gitFn = defaultGitFn }) {
+  const declared = readIdentity(projectDir);
+  const local = (key) => configValue(gitFn, projectDir, ["--local", "--get", `user.${key}`]);
+  const effective = (key) => configValue(gitFn, projectDir, ["--get", `user.${key}`]);
+  const localEmail = local("email");
+  const email = declared?.git_email ?? localEmail ?? effective("email");
+  const name = local("name") ?? effective("name");
+  if (!email || !name) return null;
+  let source = "global";
+  if (declared) source = "declared";
+  else if (localEmail) source = "repo";
+  return { name, email, source };
+}
+
+/** The environment that pins author and committer for one git command. */
+export const identityEnv = ({ name, email }) => ({
+  GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email,
+});

package/src/harden/phone-invite.js

@@ -0,0 +1,53 @@
+/**
+ * KJC-TSK-0986 (HUM-F, ADR 0018): whoever runs kj without a phone enrolled
+ * learns it once per version, not the day the maximum level (HUM-D) refuses a
+ * seal. One text, used by the SessionStart notice, by `kj doctor` and, when
+ * HUM-D lands, by the deny itself: what the signature protects, how to enroll,
+ * and how one proceeds today without it.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { isPhoneEnrolled } from "./phone-sign.js";
+import { STRATEGY } from "../checks/types.js";
+
+export const PHONE_INVITE =
+  "El móvil no está enrolado: los sellos (kj harden --commit), las aprobaciones y los comandos del catálogo se firman hoy con un código tecleado, con menos garantía. Enrólalo con kj identity enroll-phone <clave pública de la app>: cada acto queda atado a tu clave privada, que nunca sale del móvil (ADR 0018).";
+
+const markerPath = (home) => join(home ?? homedir(), ".karajan", "phone-invite.json");
+
+/**
+ * The invitation, once per kj version, or null (phone enrolled, or already said
+ * for this version). Saying it records it; a marker that cannot be written
+ * never silences the invitation.
+ * @param {{home?: string, version?: string}} [opts]
+ * @returns {string|null}
+ */
+export function phoneInvite({ home, version = "unknown" } = {}) {
+  if (isPhoneEnrolled({ home })) return null;
+  let seen = null;
+  try { seen = JSON.parse(readFileSync(markerPath(home), "utf8")).version; } catch { /* never invited */ }
+  if (seen === version) return null;
+  try {
+    mkdirSync(dirname(markerPath(home)), { recursive: true });
+    writeFileSync(markerPath(home), `${JSON.stringify({ version, at: new Date().toISOString() })}\n`, "utf8");
+  } catch { /* the invitation still goes out */ }
+  return PHONE_INVITE;
+}
+
+/** `kj doctor`: WARN while the phone is not enrolled, with the same text. */
+export function createPhoneCheck({ home } = {}) {
+  return {
+    name: "phone-enrolled",
+    label: "móvil enrolado (firma de sellos y aprobaciones)",
+    strategy: STRATEGY.MANUAL,
+    describe: "Whether a phone's public key is enrolled for the supervisor seal and approvals (ADR 0018)",
+    async detect() {
+      if (isPhoneEnrolled({ home })) return { ok: true, severity: "info", detail: "clave pública en ~/.karajan/supervisor-phone.json" };
+      return { ok: false, severity: "warn", detail: PHONE_INVITE, fix: "kj identity enroll-phone <clave pública de la app>" };
+    },
+  };
+}
+
+export const getPhoneChecks = (opts) => [createPhoneCheck(opts)];

package/src/harden/sentinel/sessionstart.mjs

@@ -38,6 +38,11 @@ process.stdin.on("end", () => {
       lines.push("Karajan (reglas que la compactación se lleva):", ...RULES, `Estado: rama ${branch}, card ${card}${unmoved}.`);
     }
     if (drift) lines.push(`Karajan: ${drift}`);
+    // KJC-TSK-0986 (HUM-F, ADR 0018): once per kj version, the invitation to
+    // enroll the phone when none is; kj decides and remembers, the hook relays.
+    const invite = spawnSync("kj", ["identity", "phone-invite"], { encoding: "utf8", timeout: 8000 });
+    const inviteText = invite.status === 0 ? String(invite.stdout || "").trim() : "";
+    if (inviteText) lines.push(`Karajan: ${inviteText}`);
     if (lines.length === 0) process.exit(0);
     process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } }));
   } catch { /* never fails a session */ }

package/src/harden/sentinel-hooks.js

@@ -570,6 +570,25 @@ process.stdin.on("end", () => {
         }
       }
     }
+    // KJC-BUG-0252 (#1899): una issue para karajan-code sale por kj report-issue
+    // (sanitiza y busca duplicados), nunca por gh issue create a mano.
+    {
+      const ghIssue = String(input.command || "");
+      if (tool === "Bash" && /(^|[^a-zA-Z])gh([^a-zA-Z]|$)/.test(ghIssue) && /(^|[^a-z])issue([^a-z]|$)/.test(ghIssue) && /(^|[^a-z])create([^a-z]|$)/.test(ghIssue)) {
+        // The target: --repo/-R, an inline or inherited GH_REPO, else the
+        // checkout's own origin, which is what gh takes (review catches).
+        const inlineRepo = /(^|[^A-Z_])GH_REPO=([^ ]+)/.exec(ghIssue);
+        let target = optionValues(ghIssue, ["--repo", "-R"]).at(-1) || (inlineRepo ? inlineRepo[2] : "") || String(process.env.GH_REPO || "");
+        if (!target) {
+          const origin = spawnSync("git", ["config", "--get", "remote.origin.url"], { cwd: ROOT, encoding: "utf8" });
+          target = String(origin.stdout || "").trim();
+        }
+        if (/karajan-code([^a-z0-9]|$)/i.test(target)) {
+          console.error("karajan sentinel: las issues para karajan-code salen por kj report-issue (sanitiza y busca issues parecidas), no por gh issue create." + doc("report-issue"));
+          process.exit(2);
+        }
+      }
+    }
     // KJC-TSK-0822 v1.1: enrolar (o pisar) la clave del movil es acto humano
     // — si un agente pudiera enrolar una clave SUYA, contestaria la capa 5 el
     // solo. Ni el comando ni el fichero de enrolamiento desde la sesion.

package/src/orchestrator/drivers/run-hu-batch.js

@@ -57,7 +57,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
   // Per-HU pipeline: focused max_iterations, fresh Brain state, own git branch.
   const huMaxIterations = ctx.config.hu_max_iterations ?? 3;
   const huBranches = new Map();
-  const { prepareHuBranch, finalizeHuCommit } = await import("../../git/hu-automation.js");
+  const { prepareHuBranch, finalizeHuCommit, collectGitWarnings } = await import("../../git/hu-automation.js");
 
   // PR F (v2.7.5): the per-HU loop needs three pieces of plan context:
   //   • ADRs (loaded once from disk, applies to every HU on this plan)
@@ -142,7 +142,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
         branchName = `kj-hu-${story.id}`;
         huBranches.set(story.id, branchName);
       } else {
-        branchName = await prepareHuBranch({ story, huBranches, config: laneConfig, logger });
+        branchName = await prepareHuBranch({ story, huBranches, config: laneConfig, logger, cardId: ctx.session?.pg_task_id || null });
       }
 
       // KJC-TSK-0408 step 2: snapshot del workspace ANTES de invocar al
@@ -257,8 +257,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             );
             if (pendingGherkinTests.length === 0) {
               logger.info(`HU ${story.id}: all shell acceptance tests PASSED, no Gherkin to translate — approved`);
-              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
-              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
+              const git = await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed", git };
             }
 
             // Shell tests passed; Gherkin needs translation. Invoke the
@@ -276,8 +276,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             const testerStage = testerOutcome?.stageResult;
             if (testerOutcome?.action !== "continue" && testerStage?.verdict === "pass") {
               logger.info(`HU ${story.id}: tester translated Gherkin and verdict=pass — approved`);
-              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
-              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
+              const git = await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed", git };
             }
 
             // Tester rejected (translated tests failed or coverage
@@ -375,7 +375,10 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
       const laneCtx = { ...ctx, config: laneConfig, pipelineFlags: laneFlags, session: laneSession, brainCtx: laneBrain, plannedTask: lanePlannedTask };
       const result = await runIterationLoop(laneCtx, { task: huTask, askQuestion, emitter, logger });
       if (result?.approved) {
-        await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+        // KJC-BUG-0248: what the HU's push or PR said joins what the loop recorded.
+        const git = await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+        const prev = result.git ?? {};
+        return { ...result, git: { ...prev, prUrl: prev.prUrl ?? git.prUrl, errors: [...(prev.errors ?? []), ...git.errors] } };
       }
       return result;
     },
@@ -415,12 +418,17 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
     }
   }
 
+  // KJC-BUG-0248 (#1895): a push or a PR that failed is said in the result
+  // the host reads, not only in a warn line of the log.
+  const warnings = collectGitWarnings(subPipelineResult.results);
+  for (const w of warnings) logger.warn(`git automation: ${w}`);
   const finalResult = {
     approved: subPipelineResult.approved,
     sessionId: ctx.session.id,
     huResults: subPipelineResult.results,
     blockedIds: subPipelineResult.blockedIds,
-    planId: ctx.session._planRef?.planId || null
+    planId: ctx.session._planRef?.planId || null,
+    ...(warnings.length > 0 ? { warnings } : {})
   };
   await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });
   return { handled: true, result: finalResult };

package/src/orchestrator/hu-sub-pipeline.js

@@ -172,6 +172,8 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
   if (Array.isArray(r.deferredIssues)) {
     for (const d of r.deferredIssues) blockers.push(typeof d === "string" ? d : d.message || JSON.stringify(d));
   }
+  // KJC-BUG-0248: a push or PR that failed is a blocker the board shows.
+  for (const e of git.errors ?? []) blockers.push(`${e.step} failed: ${e.message}. ${e.remedy}`);
   // Plain-Spanish, one-or-two sentences.
   let summary;
   if (r.review?.summary) summary = String(r.review.summary);

package/src/orchestrator/preflight-checks.js

@@ -33,6 +33,7 @@ import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
 import { getProjectChecks } from "../checks/project-checks.js";
 import { resolveTestHarness } from "../config/test-harness.js";
+import { collectGuaranteeFacts } from "../checks/guarantee-level.js";
 
 function parseJsonSafe(text) {
   try {
@@ -231,6 +232,26 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     errors: [],
   };
 
+  // KJC-BUG-0252 (#1899): on a Claude host without the Sentinel harness nothing
+  // governs the host's own actions (issues by hand, commits, pushes, merges);
+  // a run reported Tier A OFF and the agent routed around every gate. kj never
+  // fakes that supervision: the run stops here, with the remedy.
+  const guarantee = collectGuaranteeFacts({ projectDir: config.projectDir || process.cwd() });
+  if (guarantee.host === "claude" && !guarantee.tierA.active) {
+    result.ok = false;
+    result.checks.push({ name: "sentinel-harness", ok: false, detail: guarantee.tierA.reason });
+    result.errors.push({
+      check: "sentinel-harness",
+      message: "Tier A tool-time is OFF: a Claude host without the Sentinel harness, so nothing governs the host's own actions outside this run.",
+      fix: "Run kj harden (kj init installs it) and seal it with kj harden --commit; then run again.",
+    });
+    logger.error("Preflight: Sentinel harness not installed on a Claude host — run kj harden");
+    emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
+      status: "fail", message: "Preflight FAILED — Sentinel harness not installed", detail: result
+    }));
+    return result;
+  }
+
   // Resolve extended preflight opt-in early so the short-circuit below can see it.
   // Post-v2.7.5 this no longer reads globalThis directly — config.testHarness
   // is populated by the loader from the global or the default.

package/src/planning-game/pipeline-adapter.js

@@ -195,10 +195,19 @@ export function accumulateCommit(session, commitInfo) {
 // --- Internal helpers ---
 
 async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
+  const { fetchCard, updateCard } = await import("./client.js");
+  // KJC-BUG-0247 (#1894): a card that cannot be read was one warn line and
+  // null, and the run went on without the card's acceptance criteria, invented
+  // its own HUs and said approved. With a card named, no card is a loud stop.
+  let pgCard;
   try {
-    const { fetchCard, updateCard } = await import("./client.js");
-    const pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
-    if (pgCard && pgCard.status !== "In Progress") {
+    pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
+  } catch (err) {
+    throw new Error(`Planning Game: card ${pgTaskId} could not be read (${err.message}): the run would implement without the card's acceptance criteria. Check PG_API_URL, or run without pgTask.`, { cause: err });
+  }
+  if (!pgCard) throw new Error(`Planning Game: card ${pgTaskId} not found in project ${pgProject}: the run would implement without the card's acceptance criteria. Check the id, or run without pgTask.`);
+  try {
+    if (pgCard.status !== "In Progress") {
       await updateCard({
         projectId: pgProject,
         cardId: pgTaskId,
@@ -212,11 +221,11 @@ async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
       });
       logger.info(`Planning Game: ${pgTaskId} → In Progress`);
     }
-    return pgCard;
   } catch (err) {
+    // The card was read: its criteria govern the run; the status move is best-effort.
     logger.warn(`Planning Game: could not update ${pgTaskId}: ${err.message}`);
-    return null;
   }
+  return pgCard;
 }
 
 /**

package/src/utils/git.js

@@ -1,5 +1,6 @@
 import { runCommand } from "./process.js";
 import { getRunContext } from "./run-context.js";
+import { identityEnv } from "../git/run-identity.js";
 
 /**
  * Module-scoped runner — legacy back-compat for callers outside a
@@ -162,9 +163,20 @@ export async function createBranch(branchName) {
   await runGit(["checkout", "-b", branchName]);
 }
 
-export function buildBranchName(prefix, task) {
+export async function checkoutBranch(branchName) {
+  await runGit(["checkout", branchName]);
+}
+
+/**
+ * KJC-BUG-0249 (#1896): with a Planning Game card the branch carries its id,
+ * `feat/<CARD-ID>-<slug>`, the name the card-first gate reads; the stamp is
+ * for a run with no card, where nothing else makes the name unique.
+ */
+export function buildBranchName(prefix, task, cardId = null) {
+  const slug = slugifyTask(task) || "task";
+  if (cardId) return `${prefix}${cardId}-${slug}`;
   const stamp = new Date().toISOString().replaceAll(/[:.]/g, "-").slice(0, 16);
-  return `${prefix}${slugifyTask(task) || "task"}-${stamp}`;
+  return `${prefix}${slug}-${stamp}`;
 }
 
 export async function hasChanges(cwd = null) {
@@ -263,9 +275,13 @@ export async function commitAll(message, cwd = null, { beforeCommit = null, excl
   // The callback learns the exact paths, so a verdict stamped there binds to the
   // diff this commit will contain and not to whatever else the index holds.
   if (beforeCommit) await beforeCommit({ paths });
+  // KJC-BUG-0246 (#1893): every commit of a run carries the identity the run
+  // resolved once (prepareGitAutomation), never what git resolves at that moment.
+  const identity = getRunContext()?.gitIdentity;
+  const commitOpts = identity ? { ...opts, env: { ...process.env, ...identityEnv(identity) } } : opts;
   try {
     // --only: these paths and nothing else; what the person had staged stays staged.
-    await runGit(["commit", "-m", message, "--only", "--", ...paths], opts);
+    await runGit(["commit", "-m", message, "--only", "--", ...paths], commitOpts);
   } catch (err) {
     // `git status --porcelain` and `git commit` disagreed about whether
     // there was anything to commit. Don't escalate — the only outcome