@bongos/core 1.18.3 → 1.18.18

package/modules/lifecycle/done-when.js

@@ -25,6 +25,17 @@
 
 const { pool } = require('../../src/module-api');
 
+// isPendingReview — the ONE derivation of the "met — pending review" auto-flag
+// (ADR 0086 §6 / BV1.R63): a criterion with >=1 linked task, every one shipped,
+// and not yet confirmed. Pure + shared so every read model agrees — the rollup
+// below (buildCriterionProgress) and the hall's goal-detail read
+// (db.listCriteriaForGoal, task 1002164) both call it; listPendingReviewCriteria
+// expresses the same rule as a SQL HAVING clause. Counts are coerced because
+// node-postgres renders count() as a string unless cast.
+function isPendingReview({ satisfied, linked, unshipped }) {
+  return !satisfied && Number(linked) > 0 && Number(unshipped) === 0;
+}
+
 // -------------------------------------------------------------------------
 // Reads
 // -------------------------------------------------------------------------
@@ -262,9 +273,12 @@ function buildCriterionProgress(versionId, rows, unattributedCount = 0, goalRows
     // Auto-flag (ADR 0086 §6 / BV1.R63): a criterion is "met — pending review"
     // when it has ≥1 linked task and every one has shipped, but it has NOT yet
     // been confirmed (satisfied=false). Purely DERIVED — no stored column, no
-    // manual propose step. /goal-review surfaces these for a Metic+ to confirm
-    // (→ satisfied) or reject; /status renders the flag inline.
-    const pending_review = !c.satisfied && c.tasks.length > 0 && remaining.length === 0;
+    // manual propose step. /goal-review and the hall's goal-detail page (task
+    // 1002164) surface these for a Metic+ to confirm (→ satisfied) or reject;
+    // /status renders the flag inline.
+    const pending_review = isPendingReview({
+      satisfied: c.satisfied, linked: c.tasks.length, unshipped: remaining.length,
+    });
     return { ...c, counts: { ...counts, shipped, remaining: remaining.length }, remaining, pending_review };
   });
 
@@ -350,6 +364,7 @@ module.exports = {
   criterionProgress,
   buildCriterionProgress,
   buildGoals,
+  isPendingReview,
   markCriterion,
   unmarkCriterion,
 };

package/modules/lifecycle/github-push.js

@@ -383,7 +383,8 @@ async function enableAutoMerge({ nodeId }, deps = {}) {
 // getPublishStatus — report the PR + prod-deploy state so ship.js can poll
 // WITHOUT gh on the box. Returns:
 //   { pr_state, merged, merge_sha, deploy_status }  where
-//   pr_state ∈ open|closed|none, deploy_status ∈ pending|success|none.
+//   pr_state ∈ open|closed|none, deploy_status ∈ pending|success|none|unconfigured
+//   ('unconfigured' = this repo has no deploy-prod.yml — task 1002472).
 // Mirrors ship.js pollCiDeploy's two-stage check (PR merged -> deploy run).
 async function getPublishStatus({ branch }, deps = {}) {
   const token = await resolveToken(deps);
@@ -432,7 +433,17 @@ async function getPublishStatus({ branch }, deps = {}) {
         (r) => r && r.head_sha === mergeSha && r.status === 'completed' && r.conclusion === 'success'
       );
       if (hit) deployStatus = 'success';
+    } else if (runsRes.status === 404) {
+      // task 1002472 — the workflow FILE does not exist in this repo, so there is no
+      // deploy to wait for and 'pending' would never resolve. The 404 is unambiguous:
+      // the /pulls fetch above already threw STATUS_FETCH_FAILED if the repo were
+      // unreachable, so reaching here means the repo resolved and only the workflow is
+      // missing — a permanent condition. Instances that publish by pin-bump
+      // (package-core → bongos upgrade, ADR 0108) never have a deploy-prod.yml at all;
+      // reporting 'pending' pinned every merged PR at confirmed forever.
+      deployStatus = 'unconfigured';
     }
+    // Any other non-ok (5xx, 403, rate limit) is transient → stay 'pending' and retry.
   } catch (_) {
     /* leave pending on a transient runs-API miss */
   }
@@ -652,8 +663,14 @@ async function setCommitStatus({ sha, state, context, description, targetUrl },
 // publish-status route flips the task confirmed→shipped so a successful publish
 // never strands at confirmed waiting on a human to re-poll (the #1027
 // retrospective). Pure + exported so the route's reconcile trigger is unit-tested.
+// task 1002472 — 'unconfigured' (no deploy-prod.yml in the repo, see getPublishStatus)
+// counts as landed too: on an instance that publishes by pin-bump (ADR 0108) the MERGE
+// is the land, and requiring a deploy that can never run pinned every merged PR at
+// 'confirmed' forever. MERGED stays mandatory, and this is only the gate on the
+// branch/PR path — landProvenForTask still has to prove the land is THIS task's.
 function landConfirmed(status) {
-  return !!status && status.merged === true && status.deploy_status === 'success';
+  if (!status || status.merged !== true) return false;
+  return status.deploy_status === 'success' || status.deploy_status === 'unconfigured';
 }
 
 // task 1547 — is a landConfirmed status PROVEN to be THIS task's land, and not a

package/modules/lifecycle/goal-advisory.js

@@ -0,0 +1,114 @@
+// modules/lifecycle/goal-advisory.js — the ORPHAN-TASK advisory (task 1002539).
+//
+// THE HOLE. Nothing errors when a task has no goal to live in. POST /tasks with no
+// goal_id returns 201 every time: db.createTask defaults a goal-less task into its
+// version's catch-all "<version> — general" goal, and if that goal does not exist
+// the fallback is NULL and the task is created goal-less, silently.
+//
+// And for a modern version it does not exist. The catch-all rows were created ONLY
+// by migrations/160_goal_tier.sql, by selecting over the `versions` table AT THAT
+// MOMENT. db.createVersion does not create one and there is no trigger — so every
+// version created after migration 160 gives each of its tasks goal_id = NULL, with
+// no signal to anyone. A task with no goal has no scope wall, no done-when criteria
+// gating it, and no workspace it gets reviewed in (ADR 0086 §2).
+//
+// This module makes that visible WITHOUT blocking anything: POST /tasks attaches
+// the verdict to its 201 body as `goal_advisory`, the /goal-create skill picks it
+// up, and a task that lands somewhere real gets `null` — silence.
+//
+// PURE + exported so every branch is pinned by a DB-free unit test (the
+// criterion-suggest / goal-authz precedent). A module sibling, like ../db.
+
+// The catch-all goal migration 160 created per version. ONE definition, shared with
+// db.generalGoalIdForVersion, which used to spell it inline under a "keep the two in
+// sync" comment. The dash is an EM DASH (U+2014) with spaces either side — an ASCII
+// hyphen or an en dash is a different, ordinary goal and must not match.
+function generalGoalTitle(versionId) {
+  return `${versionId} — general`;
+}
+
+// adviseGoal — PURE, FAIL-OPEN. Returns null when the task has a real home, or the
+// advisory body when it does not. Two reasons, checked in order:
+//
+//   no_goal   — goal_id is NULL. The version has no catch-all at all (created after
+//               migration 160), so the task is structurally orphaned.
+//   catch_all — the task landed in "<version> — general": a bucket, not a workspace.
+//               No scope wall, no criteria, no members, no review. Better than NULL,
+//               still not a home.
+//
+// Fail-OPEN on ambiguity (return null, say nothing) — the opposite posture from an
+// authorization gate. This is advice appended to a request that ALREADY SUCCEEDED;
+// a wrong guess here nags a builder about a task that is fine, which is worse than
+// staying quiet. A missing versionId or an unreadable goal title yields null.
+function adviseGoal({ versionId, goalId, goalTitle } = {}) {
+  if (goalId == null) {
+    return {
+      reason: 'no_goal',
+      message: 'This task has no goal to live in — no scope wall, no done-when criteria gating it, '
+        + 'and no workspace it gets reviewed in (ADR 0086 §2). Its version has no catch-all goal, '
+        + 'which is normal for any version created after the goal tier shipped.',
+      version_id: versionId ?? null,
+      goal_id: null,
+    };
+  }
+  if (versionId == null || typeof goalTitle !== 'string') return null;
+  if (goalTitle !== generalGoalTitle(versionId)) return null;
+  return {
+    reason: 'catch_all',
+    message: `This task landed in "${goalTitle}", the version's catch-all bucket rather than a real goal — `
+      + 'no scope wall, no criteria, and no owner reviewing it.',
+    version_id: versionId,
+    goal_id: goalId,
+  };
+}
+
+// candidateGoals — PURE. The version's OPEN goals minus the catch-all, shaped down
+// to what a caller needs to choose a home. Order is preserved (listGoals already
+// sorts by sort_order), so the caller can trust the first entries are the ranked
+// ones. Non-array input yields [] rather than throwing — same fail-open posture.
+function candidateGoals(goals, versionId) {
+  if (!Array.isArray(goals)) return [];
+  const catchAll = versionId == null ? null : generalGoalTitle(versionId);
+  return goals
+    .filter((g) => g && g.title !== catchAll)
+    .map((g) => ({ id: g.id, title: g.title, scope_modules: g.scope_modules || [] }));
+}
+
+// How many alternative goals the advisory offers. Small on purpose — this is a hint
+// for a human/agent choosing a home, not a browsable list.
+const CANDIDATE_LIMIT = 5;
+
+// buildGoalAdvisory — the whole advisory, DB reads included, so POST /tasks calls one
+// line and this is directly unit-testable with a stub db (no route simulation).
+//
+// It swallows its own failures on purpose. The task row is ALREADY COMMITTED when
+// this runs, so a throw would turn a created task into a 500 that the caller then
+// retries — and source_ref idempotency only saves callers who set one, so a bare
+// retry mints a DUPLICATE task. Degrading to null (silence) is always correct here.
+// Only the unhappy path pays for the second query.
+async function buildGoalAdvisory({ db, versionId, task }) {
+  try {
+    const homeGoal = task.goal_id != null ? await db.getGoal(task.goal_id) : null;
+    const verdict = adviseGoal({
+      versionId,
+      goalId: task.goal_id,
+      goalTitle: homeGoal && homeGoal.title,
+    });
+    if (!verdict) return null;
+    // LIMIT 6, not 6-in-JS: Postgres truncates instead of shipping every open goal
+    // on the version to be discarded here. Six because candidateGoals drops the
+    // catch-all, so 6 rows still guarantee the 5 candidates below.
+    const open = await db.listGoals({ versionId, status: 'open', limit: CANDIDATE_LIMIT + 1 });
+    return {
+      ...verdict,
+      candidate_goals: candidateGoals(open, versionId).slice(0, CANDIDATE_LIMIT),
+      next_step: 'Run /goal-create to plan a goal for this work, or file it under an existing one: '
+        + `PATCH /tasks/${task.id} {"goal_id": <id>}`,
+    };
+  } catch (e) {
+    console.error('[gds] goal-advisory (non-blocking)', e && e.message);
+    return null;
+  }
+}
+
+module.exports = { adviseGoal, candidateGoals, generalGoalTitle, buildGoalAdvisory };

package/modules/lifecycle/goal-authz.js

@@ -0,0 +1,62 @@
+// modules/lifecycle/goal-authz.js — the goal AUTHORITY MODEL, as pure functions.
+//
+// Extracted from routes/goals.js (task 1002538 / ADR 0154) so a SECOND route can
+// share it: POST /versions/:id/done-when now lets a goal's own authority author
+// that goal's criteria, and authorization logic must have exactly one definition.
+// routes/goals.js re-exports authorizeGoalManagement (isGoalOwner it imports for
+// internal use only), so its existing DB-free unit tests (goal_conflicts,
+// goal_member_roles, goal_membership_requests) are unchanged.
+//
+// A module sibling, like ../goal-conflicts — routes consume pure files here; no
+// route requires another route.
+
+// The goal AUTHORITY MODEL (task 1735). Two layers, deliberately different kinds:
+//   - OWNER — goals.created_by, the fixed authority. Not a role row: it is set at
+//     create time (the creator) and moves only via the explicit transfer route.
+//     The owner holds every goal power.
+//   - MANAGER — the goal_members.role 'lead' value (the hall renders it
+//     "manager"). Owner-equivalent EXCEPT: a manager cannot DEMOTE a fellow
+//     manager (owner-only), and cannot transfer ownership.
+// A goal with created_by NULL (the migration-160 system defaults) has no owner;
+// Archons act as one — the archon arm of both gates below.
+function isGoalOwner(goal, builderId) {
+  return goal.created_by != null && String(goal.created_by) === String(builderId);
+}
+
+// isGoalOwnerOrManager — the AUTHORITY predicate on its own, with no goal-state
+// check in front of it. authorizeGoalManagement answers "may this actor manage
+// this goal *right now*" (state first, so an owner gets a useful goal_not_open);
+// a caller that must not LEAK the goal's existence needs the authority question
+// alone, asked first. ADR 0154: POST /versions/:id/done-when uses this to mask an
+// unauthorized caller behind the same 400 as a non-existent goal.
+function isGoalOwnerOrManager({ goal, actorId, actorRank, actorMembership }) {
+  if (actorRank === 'archon') return true;
+  if (!goal) return false;
+  return isGoalOwner(goal, actorId) || (!!actorMembership && actorMembership.role === 'lead');
+}
+
+// authorizeGoalManagement — the shared ORDERED, FAIL-CLOSED prefix for actions
+// a goal's own authority performs (task 1736: conflict resolution; the same
+// three steps open authorizeMemberRoleChange): goal exists → goal open →
+// actor is owner|manager|Archon. Returns { ok:true } or { ok:false, status,
+// body }. PURE + exported, same precedent as its siblings.
+function authorizeGoalManagement({ goal, actorId, actorRank, actorMembership }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Only an open goal can be managed.',
+    } };
+  }
+  if (!isGoalOwnerOrManager({ goal, actorId, actorRank, actorMembership })) {
+    return { ok: false, status: 403, body: {
+      error: 'not_owner_or_manager',
+      message: 'Only this goal\'s owner or a manager (or an Archon) may do this.',
+    } };
+  }
+  return { ok: true };
+}
+
+module.exports = { isGoalOwner, isGoalOwnerOrManager, authorizeGoalManagement };

package/modules/lifecycle/lifecycle.js

@@ -48,6 +48,10 @@ module.exports = {
   recentGradesForBuilder: (...a) => db.recentGradesForBuilder(...a),
   countShippedTasksForBuilder: (...a) => db.countShippedTasksForBuilder(...a),
   recentShippedTasksByBuilder: (...a) => db.recentShippedTasksByBuilder(...a),
+  // ADR 0120 part 5: the confirmed tasks a builder owes a rebase on — the same
+  // read the part-3 claim gate uses, surfaced to me.js so the CLI + hall can
+  // show the owed-rebase warning that gates new claims (reward lands on ship).
+  needsRebaseTasksForBuilder: (...a) => db.needsRebaseTasksForBuilder(...a),
   // builders.js (the Archon roster): the roster + stale-claim + per-builder grade.
   getBuildersRoster: (...a) => db.getBuildersRoster(...a),
   getActiveClaimsForBuilderWithStale: (...a) => db.getActiveClaimsForBuilderWithStale(...a),
@@ -55,4 +59,9 @@ module.exports = {
   // analytics.js (the AI-dev-curve): the builder + ecosystem analytics.
   builderAnalytics: (...a) => db.builderAnalytics(...a),
   ecosystemAnalytics: (...a) => db.ecosystemAnalytics(...a),
+  // dev-box (modules/dev-box/routes/box.js, via resolveOptional('lifecycle')): the
+  // module-key scope of a builder's active claims — the task-scoped source-access
+  // resolver (goal 1000051 / R92, ADR 0148 §2). Keys only; box-access maps them to
+  // git sparse-checkout globs through the doorway `moduleScopeMap`.
+  moduleScopeForActiveClaims: (...a) => db.moduleScopeForActiveClaims(...a),
 };

package/modules/lifecycle/publish-reconciler.js

@@ -72,6 +72,12 @@ const healAttempts = new Map(); // branch -> regen-heal attempts this process
 
 let intervalTimer = null;
 let firstTimer = null;
+// task 1002461: the no-credential skip is WARN'd once per unconfigured streak, not
+// once per tick — a 5-min poller would otherwise bury the journal. Re-armed by any
+// sweep that proceeds, so a credential LOSS after a healthy period is reported.
+// Injectable (deps.warnState) for the same reason healAttempts is: the tests in this
+// suite run concurrently, so a shared module latch would leak across them.
+const warnState = { unconfigured: false };
 
 // task 1915 — is this mergeIfGreen result the "mergeable but a check is RED" shape
 // whose commonest cause is a STALE generated index (see refreshStaleGenerated)? Only
@@ -86,6 +92,32 @@ function couldBeStaleGenerated(m) {
   return /^failing_check:/.test(reason) || /^non_required_check_failing:/.test(reason);
 }
 
+// task 1002461 — render the reconciler's operating target: which repo it resolved
+// and whether it holds a credential. This is the line that makes a WRONG repo bind
+// visible without owner access (the live failure: the hub bound
+// cloudbongos/cloudbongos-instance while the PRs were in lars589/cloud-bongos).
+// Pure — takes the resolved facts, returns the string — so the wording is
+// unit-tested without a boot.
+function describeTarget({ configured, repo } = {}) {
+  const cred = configured ? 'credential present' : 'NO PUSH CREDENTIAL';
+  if (!repo || repo.error) {
+    return `target: UNRESOLVED (${(repo && repo.detail) || (repo && repo.error) || 'no repo info'}) · ${cred}`;
+  }
+  return `target: ${repo.owner}/${repo.repo} (branch ${repo.branch || 'main'}) · ${cred}`;
+}
+
+// Resolve the repo the reconciler would act on, never throwing — an observability
+// helper must not be able to break the sweep it is describing. `deps.repoInfo` is
+// the test seam.
+function resolveTarget(deps = {}) {
+  if (deps.repoInfo) return deps.repoInfo;
+  try {
+    return seams.repoInfo.loadRepoInfo();
+  } catch (e) {
+    return { error: 'lookup_failed', detail: e && e.message };
+  }
+}
+
 // One sweep. Pure w.r.t. injected deps (db / githubPush / emit / loggers)
 // so the whole thing is unit-tested with no DB and no network. Returns a summary
 // { skipped?, checked, reconciled, errors } for observability + tests.
@@ -99,9 +131,23 @@ async function runSweep(deps = {}) {
 
   // No server push credential (local dev, tests, an un-provisioned host) → there
   // is nothing to reconcile against, and getPublishStatus would 503. No-op.
+  //
+  // task 1002461: this used to return SILENTLY while start() logged "started —
+  // sweeping confirmed→shipped every Ns", so the journal showed a healthy poller
+  // that could never land anything — the stranding went unnoticed for 6+ days. Say
+  // it, once per unconfigured streak, and name the repo so a wrong bind shows up in
+  // the same line.
+  const warn = deps.warnState || warnState;
   if (!push.isConfigured()) {
+    if (!warn.unconfigured) {
+      warn.unconfigured = true;
+      errFn(
+        `[publish-reconciler] WARN ${describeTarget({ configured: false, repo: resolveTarget(deps) })} — confirmed→shipped can NEVER land until a credential is set (GITHUB_APP_ID + GITHUB_APP_INSTALLATION_ID + GITHUB_APP_PRIVATE_KEY, or GITHUB_PUSH_TOKEN). Subsequent sweeps stay quiet until this changes.`
+      );
+    }
     return { skipped: 'unconfigured', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 0 };
   }
+  warn.unconfigured = false; // re-arm: a later credential LOSS must warn again
 
   let rows;
   try {
@@ -146,6 +192,10 @@ async function runSweep(deps = {}) {
     let landed = false;
     let landNote = '';
     let branchStatus = null;
+    // task 1002472 — set when a PR exists but has not fully landed. Suppresses the
+    // land proof (an open PR must never ship) WITHOUT suppressing the observability
+    // below, which the old bare `continue` did.
+    let prNotLanded = false;
 
     if (branchUsable) {
       // Active merge driver (task 1162): GitHub's auto-merge fires on check-completion
@@ -209,6 +259,17 @@ async function runSweep(deps = {}) {
               logFn(
                 `[publish-reconciler] task ${r.task_id} (${branch}) PR #${m.number} still red after ${n} regen-heal attempt(s) (${m.reason}) — capped (persistent staleness treadmill or a real check failure); left for a human`
               );
+              // ADR 0120 part 2: the auto-land grace (retries + ADR 0082 self-heal)
+              // is exhausted and the PR is still red — a real check failure or a
+              // hand-written conflict only the builder can resolve. Flag needs_rebase
+              // so their queue is gated until they fix + re-land (or release it).
+              try {
+                if (await db.flagTaskNeedsRebase(r.task_id, `failing_check_capped:${m.reason}`)) {
+                  logFn(`[publish-reconciler] task ${r.task_id} flagged needs_rebase (regen-heal cap) — its builder must fix + re-land`);
+                }
+              } catch (e) {
+                errFn(`[publish-reconciler] flagNeedsRebase (cap) task ${r.task_id} (non-blocking): ${e && e.message}`);
+              }
             } else {
               try {
                 const rr = await resolver.refreshStaleGenerated({ branch });
@@ -247,7 +308,14 @@ async function runSweep(deps = {}) {
       if (!push.landConfirmed(status) && status && status.pr_state !== 'none') {
         // A PR exists but hasn't fully landed yet (open / merged-but-deploy-pending /
         // blocked). Respect it — wait for the deploy — rather than risk shipping early.
-        continue;
+        //
+        // task 1002472: this used to be a bare `continue`, which jumped PAST the
+        // unprovable counter, the STALE WARN and flagTaskNeedsRebase below — so this
+        // strand shape was completely invisible (tasks 1002427/1002428 sat 50h at
+        // 'confirmed' reporting needs_rebase:false). Flag it instead and fall through
+        // to the observability block. The flag still suppresses the land proof, so an
+        // un-landed PR is no more shippable than it was.
+        prNotLanded = true;
       }
       branchStatus = status;
     }
@@ -262,7 +330,7 @@ async function runSweep(deps = {}) {
     // references this task id. landProvenForTask still cures the task-1313 strand class
     // (PR deleted post-merge / no worktree_name / ambiguous branch) — now keyed on the
     // unambiguous published tip rather than the base.
-    if (!landed && typeof push.landProvenForTask === 'function') {
+    if (!landed && !prNotLanded && typeof push.landProvenForTask === 'function') {
       try {
         const proof = await push.landProvenForTask({
           taskId: r.task_id, publishedSha: r.published_head_sha, status: branchStatus,
@@ -284,12 +352,31 @@ async function runSweep(deps = {}) {
       // (codeless confirm, or a land whose published tip was never recorded on the
       // claim) now surfaces in the logs instead of stranding silently.
       unprovable++;
-      const reason = (!branch && !r.published_head_sha) ? 'no_branch_no_tip' : 'land_not_proven';
+      // task 1002472: 'pr_not_landed' distinguishes "a PR exists and we are waiting on
+      // it" from "we looked for proof and found none" — the two need different
+      // remediation (wait/unblock the PR vs. push or rebase the branch).
+      const reason = prNotLanded
+        ? 'pr_not_landed'
+        : (!branch && !r.published_head_sha) ? 'no_branch_no_tip' : 'land_not_proven';
       const ageMs = r.confirmed_at ? (nowMs - new Date(r.confirmed_at).getTime()) : null;
       if (ageMs != null && ageMs > STALE_CONFIRMED_MS) {
         staleStrands++;
+        // ADR 0120 part 2: an aged-out, unprovable confirmed task is a strand
+        // whose land its BUILDER must complete — rebase a branch gone stale after
+        // a big codebase change, or push a branch that only ever lived on their
+        // machine (the `no_branch_no_tip` case). Flag needs_rebase (attributed via
+        // shipped_by = the claim holder); the claim gate then blocks that builder's
+        // NEW claims until they land or release it. Since the reward now lands only
+        // on ship (part 1), they are motivated to clear it. NOTE it is no longer
+        // "credited" — part 1 moved the payout from confirm to the land.
+        let flagged = false;
+        try {
+          flagged = await db.flagTaskNeedsRebase(r.task_id, `strand:${reason}`);
+        } catch (e) {
+          errFn(`[publish-reconciler] flagNeedsRebase (strand) task ${r.task_id} (non-blocking): ${e && e.message}`);
+        }
         errFn(
-          `[publish-reconciler] STRAND task ${r.task_id}: confirmed ~${Math.round(ageMs / 3_600_000)}h ago, unprovable (${reason}) — credited but no landed proof; needs owner triage`
+          `[publish-reconciler] STRAND task ${r.task_id}: confirmed ~${Math.round(ageMs / 3_600_000)}h ago, unprovable (${reason}) — no landed proof; ${flagged ? 'flagged needs_rebase for its builder' : 'needs_rebase already set'}`
         );
       }
       continue;
@@ -399,8 +486,16 @@ function start(deps = {}) {
   intervalTimer = setInterval(tick, INTERVAL_MS);
   if (intervalTimer.unref) intervalTimer.unref();
 
+  // task 1002461: the bare "started" line was actively misleading — it printed the
+  // same whether the poller could work or not. Always state the resolved target +
+  // credential alongside it, so a wrong repo bind or a missing credential is
+  // visible at boot instead of needing a simulation to prove. loadRepoInfo caches
+  // on first call, so this is also the value every later sweep uses (an env change
+  // needs a service restart to take effect).
+  const push = deps.githubPush || githubPush; // same resolution runSweep uses
+  const target = describeTarget({ configured: push.isConfigured(), repo: resolveTarget(deps) });
   console.log(
-    `[publish-reconciler] started — sweeping confirmed→shipped every ${Math.round(INTERVAL_MS / 1000)}s`
+    `[publish-reconciler] started — sweeping confirmed→shipped every ${Math.round(INTERVAL_MS / 1000)}s · ${target}`
   );
 }
 
@@ -415,4 +510,12 @@ function stop() {
   }
 }
 
-module.exports = { start, stop, runSweep, runCostSweep, couldBeStaleGenerated, INTERVAL_MS };
+module.exports = {
+  start,
+  stop,
+  runSweep,
+  runCostSweep,
+  couldBeStaleGenerated,
+  describeTarget,
+  INTERVAL_MS,
+};

package/modules/lifecycle/routes/claims.js

@@ -41,28 +41,38 @@ function taskNotReadyHint(taskId, currentStatus) {
     : `Task #${idNum} is '${currentStatus}', not 'ready' — only 'ready' tasks are claimable (promote applies to 'backlog': POST /api/bongos/tasks/${idNum}/promote).`;
 }
 
-// task 1642 — the pure session-scoped one-active-claim decision. Working two
-// tasks from one worktree means every commit lands on the single branch that
-// worktree owns; /builder-ship publishes the whole branch, so shipping one task
-// drags the other's commits with it (commingled ships). The structural cure: a
-// CLI session (≈ one worktree) may hold at most ONE active claim at a time.
+// task 1642 (+ the worktree-keying fix) — the pure one-active-claim decision.
+// Working two tasks from one WORKING TREE means every commit lands on the single
+// branch that tree owns; /builder-ship publishes the whole branch, so shipping one
+// task drags the other's commits with it (commingled ships). The structural cure:
+// a working tree may hold at most ONE active claim at a time.
 //
-// Keyed on creator_session_id, NOT builder id — a builder may run many sessions
-// in parallel, each with its own worktree and exactly one claim; that norm must
-// keep working. Session-scoped, all ranks (generalizes the old Xenos-only,
-// builder-scoped gateNewcomerClaim).
+// The hazard boundary is the WORKING TREE (one worktree = one branch = one HEAD),
+// NOT the auth session. Originally this keyed on creator_session_id — but that is
+// the AUTH-TOKEN session, which a builder shares across EVERY concurrent worktree
+// on one login (the CLI token lives in ~/.config, not per-worktree). So the guard
+// wrongly blocked the second of two genuinely-parallel worktrees — contradicting
+// its own stated intent ("a builder may run many sessions in parallel, each with
+// its own worktree and exactly one claim; that norm must keep working"). The fix:
+// scope refusal to the SAME working tree. Two claims can coexist for one auth
+// session AS LONG AS they land in different worktrees; a second claim into the
+// SAME tree (or a second worktree-less claim off one plain clone, where the single
+// branch really would commingle) is still refused.
 //
-// NULL-session handling: a web claim (bind_session=false) stores
-// creator_session_id=NULL and is adoptable by any of the builder's CLI sessions.
-// We MUST skip the check when the *incoming* claim has no session (nothing to
-// scope to) — the caller passes creatorSessionId=null and we allow. The DB
-// helper that feeds activeClaimsForSession already filters to the SAME non-null
-// session, so a pile of NULL-session web claims can never count against a CLI
-// session either.
+// `worktreeName` is the incoming claim's worktree (claims.worktree_name — the CLI
+// sends it; the server enforces its cross-active-claim uniqueness, V3.R51/#270).
+// Two trees are "the same" iff their worktree_names are equal, OR both are null
+// (no worktree info → assume one shared clone → commingle risk).
+//
+// NULL-session handling is unchanged: a web claim (bind_session=false) stores
+// creator_session_id=NULL and is adoptable by any of the builder's CLI sessions —
+// the incoming caller passes creatorSessionId=null and we allow (nothing to scope).
+// The DB helper filters activeClaimsForSession to the SAME non-null session, so a
+// pile of NULL-session web claims can never count against a CLI session either.
 //
 // Pure + exported so the decision is unit-testable without a DB or a route.
 // Returns { refuse, inFlightTaskId, inFlightTitle, reason }.
-function shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId }) {
+function shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId, worktreeName = null }) {
   // No session to scope to (web/unbound claim, or a CLI caller with no session):
   // there is nothing this guard can key on — let it through. The per-task unique
   // index and the newcomer gate still apply.
@@ -70,10 +80,19 @@ function shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId })
     return { refuse: false, inFlightTaskId: null, inFlightTitle: null, reason: null };
   }
   const claims = Array.isArray(activeClaimsForSession) ? activeClaimsForSession : [];
-  // Defence in depth: only count claims that actually belong to THIS session and
-  // are genuinely session-bound. A NULL-session row must never trip the block.
+  const incomingTree = worktreeName == null ? null : worktreeName;
+  // Two claims share a WORKING TREE iff their worktree_names match, or both are
+  // null (a worktree-less clone — the single branch genuinely commingles).
+  const sameWorkingTree = (name) => {
+    const t = name == null ? null : name;
+    return t === incomingTree;
+  };
+  // Defence in depth: only count claims that belong to THIS session, are genuinely
+  // session-bound (a NULL-session row must never trip the block), AND would land in
+  // the SAME working tree as the incoming claim.
   const inFlight = claims.find(
     (c) => c && c.creator_session_id != null && c.creator_session_id === creatorSessionId
+             && sameWorkingTree(c.worktree_name ?? null)
   );
   if (inFlight) {
     return {
@@ -100,18 +119,23 @@ async function gateOneActiveClaimPerSession(req, res, next) {
   // never do a needless lookup and never block a web claim.
   const creatorSessionId = resolveCreatorSessionId(req.body?.bind_session, req.gdsSession?.session_id);
   if (!creatorSessionId) return next();
+  // The incoming claim's working tree — the hazard boundary the guard keys on. A
+  // second claim in a DIFFERENT worktree is safe (different branch); only a second
+  // claim into the SAME tree (or off one worktree-less clone) commingles.
+  const worktreeName = req.body?.worktree_name ?? null;
   let activeClaimsForSession;
   try {
     activeClaimsForSession = await db.getActiveClaimsForSession(creatorSessionId);
   } catch (err) {
     // FAIL-CLOSED. A lookup failure must not let a commingling second claim land.
     console.error('[gds] gateOneActiveClaimPerSession lookup failed (failing closed):', err);
-    return res.fail('session_claim_check_failed', { status: 409, message: 'Could not verify this session has no other claim in flight. Try again, or start a fresh session/worktree for this task.' });
+    return res.fail('session_claim_check_failed', { status: 409, message: 'Could not verify this worktree has no other claim in flight. Try again, or start a fresh worktree for this task.' });
   }
-  const decision = shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId });
+  const decision = shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId, worktreeName });
   if (decision.refuse) {
     const n = decision.inFlightTaskId;
-    return res.fail('session_already_has_active_claim', { status: 409, message: `This session already has task ${n} in flight — ship or release it first, or start a new session/worktree for this one.`, details: { active_task_id: n, active_task_title: decision.inFlightTitle, what_to_do: `Run /builder-ship ${n} (or /builder-release ${n}) before claiming new work, or open a fresh worktree/session for this task.` } });
+    const where = worktreeName ? `worktree "${worktreeName}"` : 'this worktree';
+    return res.fail('session_already_has_active_claim', { status: 409, message: `${where} already has task ${n} in flight — ship or release it first, or claim this one from a different worktree.`, details: { active_task_id: n, active_task_title: decision.inFlightTitle, worktree_name: worktreeName, what_to_do: `Run /builder-ship ${n} (or /builder-release ${n}) before claiming new work in ${where}, or open a separate worktree for this task (each worktree may hold one claim).` } });
   }
   next();
 }
@@ -206,7 +230,18 @@ module.exports = function buildClaimsRouter() {
       // silently disambiguated it (e.g. "foo" → "foo-2") and the claim still
       // succeeded — so the caller must read claim.worktree_name back, not assume
       // it got the name it asked for.
-      res.status(201).json({ claim, task, just_unlocked: justUnlocked ?? [], overlap_warning: overlapWarning ?? null });
+      // ADR 0146 / task 1002469: ride the instance's resolved reward policy along
+      // with the claim so the CLI banner can label `task.credits_reward` honestly
+      // in the same breath it advertises it. A cost-plus-only instance never pays
+      // that estimate, and the claim banner is where the expectation forms.
+      // Resolved by economy (never re-derived); null when economy is disabled.
+      let rewardMode = null;
+      try {
+        const rw = seams.resolveOptional('reward');
+        const p = rw && typeof rw.rewardConfig === 'function' ? rw.rewardConfig() : null;
+        if (p && typeof p.mode === 'string') rewardMode = { mode: p.mode, perTaskCredit: p.perTaskCredit !== false };
+      } catch (_) { /* display-only: a claim must never fail over this */ }
+      res.status(201).json({ claim, task, just_unlocked: justUnlocked ?? [], overlap_warning: overlapWarning ?? null, reward: rewardMode });
     } catch (err) {
       if (err && err.code) {
         const status =
@@ -215,6 +250,10 @@ module.exports = function buildClaimsRouter() {
           err.code === 'TOUCHES_CONFLICT' ? 409 :
           err.code === 'MODULE_CONFLICT' ? 409 :
           err.code === 'DEPS_NOT_SHIPPED' ? 409 :
+          // ADR 0120 part 3: the builder owes a rebase on an un-landed confirmed
+          // task (reconciler-flagged needs_rebase); NEW claims are gated until
+          // they land or release it. Existing claims are unaffected.
+          err.code === 'REBASE_REQUIRED' ? 409 :
           // task 1670 / ADR 0096: an unrewarded (0/NULL credits_reward) task can't
           // be claimed — the claim-time backstop to the promote gate. Grandfathered
           // tasks (already 'ready' at migration 177) are exempt and never reach here.
@@ -236,6 +275,12 @@ module.exports = function buildClaimsRouter() {
         if (err.code === 'TASK_NOT_READY') {
           err.hint = taskNotReadyHint(taskId, err.currentStatus);
         }
+        // ADR 0120 part 3: name the offending task(s) + the two ways to clear the
+        // gate, so the builder isn't left guessing why their claim was refused.
+        if (err.code === 'REBASE_REQUIRED') {
+          const ids = (err.rebaseTasks || []).map((t) => `task ${t.id}`);
+          err.hint = `Your queue is gated: ${ids.length} confirmed task(s) await your rebase (${ids.join(', ') || 'unknown'}). Land each (rebase its branch + re-ship, or /merge-mode) — or /builder-release it — then claim new work.`;
+        }
         return res.fail(err.code, status, { ...err });
       }
       console.error('[gds] POST /claims', err);