@bongos/core 1.19.279 → 1.19.281

package/modules/hall-ui/public/goals-lib.js

@@ -0,0 +1,99 @@
+// goals-lib.js — the Goals page's PURE presentational helpers, exposed as
+// window.OTBGoalsLib. Carved out of the oversized goals-page.js (task 1003135;
+// the fitness excess-lines ratchet). Everything here is a pure function over
+// its arguments (or a constant) — no `state`, no DOM reads — so it can move
+// without dragging the page's IIFE state along. Loaded by goals.html BEFORE
+// goals-page.js (the task-lib.js / hall-kit.js pattern, tasks 1002463 / 2171).
+(function () {
+  'use strict';
+
+  // Settled task statuses (paid or awaiting land) vs terminal "deliberately
+  // cut" states — neither work-to-do nor done. CUT is excluded from the todo
+  // list and the conflict scan the same way migration 017 keeps them out of
+  // version_progress ("abandoned is a terminal state (deliberately cut), not
+  // pending work"). Without this, an abandoned task shows up under a goal's
+  // "Work to do" as if it were still queued.
+  const DONE_STATUSES = new Set(['completed', 'confirmed', 'shipped']);
+  const CUT_STATUSES = new Set(['abandoned', 'dropped']);
+  // Genuinely-open work under a goal: not done, not cut → {backlog, ready,
+  // active, blocked}.
+  const isTodoStatus = (s) => !DONE_STATUSES.has(s) && !CUT_STATUSES.has(s);
+
+  // The criteria progress ring (satisfied/total), green once achieved.
+  function ring(satisfied, total, achieved, size = 42) {
+    const pct = total > 0 ? satisfied / total : (achieved ? 1 : 0);
+    const r = 16;
+    const circ = 2 * Math.PI * r;
+    const dash = (pct * circ).toFixed(1);
+    const gap = (circ - pct * circ).toFixed(1);
+    const stroke = achieved ? 'var(--ok)' : 'var(--accent)';
+    return `<svg class="goal-ring" width="${size}" height="${size}" viewBox="0 0 42 42" role="img" aria-label="${satisfied} of ${total} criteria satisfied">
+        <circle cx="21" cy="21" r="${r}" fill="none" stroke="var(--rule-soft)" stroke-width="4"></circle>
+        <circle cx="21" cy="21" r="${r}" fill="none" stroke="${stroke}" stroke-width="4" stroke-linecap="round" stroke-dasharray="${dash} ${gap}" transform="rotate(-90 21 21)"></circle>
+        <text x="21" y="25" text-anchor="middle" class="goal-ring__label">${satisfied}/${total}</text>
+      </svg>`;
+  }
+
+  function memberName(m) {
+    return m.display_name || (m.github_login ? `@${m.github_login}` : `builder #${m.builder_id}`);
+  }
+
+  // ---- task-readiness rollup (hall redesign task 1002439) -------------------
+  // Dependencies are a TASK property; a goal is only "blocked" in the derived
+  // sense that all its actionable tasks wait on upstream tasks (the Tasks page,
+  // not this one, owns the actual task→task graph). So the Goals page rolls each
+  // goal's tasks into these buckets:
+  //   done     — settled (shipped/confirmed/completed)
+  //   active   — a live claim ("in progress")
+  //   ready    — claimable now (deps met + promoted)
+  //   blocked  — backlog with ≥1 unshipped dependency
+  //   backlog  — backlog, no unmet deps (just not started/promoted)
+  function readinessOf(t) {
+    const s = t.status;
+    if (DONE_STATUSES.has(s)) return 'done';
+    if (CUT_STATUSES.has(s)) return 'cut';
+    if (s === 'active') return 'active';
+    if (s === 'ready') return 'ready';
+    if (s === 'backlog' && (t.blocked_by || []).some((d) => !d.satisfied)) return 'blocked';
+    return 'backlog';
+  }
+  const EMPTY_ROLLUP = { done: 0, active: 0, ready: 0, blocked: 0, backlog: 0, cut: 0, total: 0, nextReady: null };
+
+  // task 1002439 — a goal row's readiness rollup line (only the non-zero buckets).
+  const ROLL_DOTS = [
+    ['ready', 'ready', 'var(--ok)'],
+    ['active', 'in progress', 'var(--info)'],
+    ['blocked', 'blocked', 'var(--terracotta)'],
+    ['backlog', 'backlog', 'var(--ink-faint)'],
+  ];
+  function goalRollLine(r) {
+    const parts = ROLL_DOTS.filter(([k]) => r[k] > 0)
+      .map(([k, label, c]) => `<span class="gr-d"><i style="background:${c}"></i><b>${r[k]}</b> ${label}</span>`);
+    return parts.length ? `<div class="gr-roll">${parts.join('')}</div>` : '';
+  }
+
+  // Free-text search over a goal's todo list (work.js:261-274, minus the
+  // goal-title match — a single goal makes that redundant). '#N', 'N' and a
+  // bare number all match the id.
+  function matchesTodoSearch(t, q) {
+    if (!q) return true;
+    const needle = q.replace(/^#/, '');
+    if (!needle) return true;
+    if (String(t.id).includes(needle)) return true;
+    if ((t.title || '').toLowerCase().includes(needle)) return true;
+    return false;
+  }
+
+  // ms helpers for the goal ordering (task 1002965): updated_at moves on every
+  // task write, shipped_at folded in because a ship path can stamp it without
+  // touching updated_at.
+  const msOf = (iso) => { const t = iso ? Date.parse(iso) : NaN; return Number.isNaN(t) ? 0 : t; };
+  const taskActivityMs = (t) => Math.max(msOf(t.updated_at), msOf(t.shipped_at));
+
+  window.OTBGoalsLib = {
+    DONE_STATUSES, CUT_STATUSES, isTodoStatus,
+    ring, memberName,
+    readinessOf, EMPTY_ROLLUP, goalRollLine,
+    matchesTodoSearch, msOf, taskActivityMs,
+  };
+})();

package/modules/hall-ui/public/goals-page.js

@@ -35,13 +35,18 @@
   // empty/skeleton states — adopted here by task 2171.
   const { makePager, paginate, wirePager, pagerBarHtml, makeTabs, makeFilterBar,
     emptyStateHtml, skeletonRows } = window.OTBKit;
+  // This page's pure presentational helpers (goals-lib.js, task 1003135 — carved
+  // out of this oversized file; the fitness excess-lines ratchet). Destructured
+  // so every call site below reads exactly as before.
+  const { DONE_STATUSES, CUT_STATUSES, isTodoStatus, ring, memberName,
+    readinessOf, EMPTY_ROLLUP, goalRollLine, matchesTodoSearch,
+    msOf, taskActivityMs } = window.OTBGoalsLib;
   const API = '/api/bongos';
   // Generated typed client (task 1996 / R09), served as window.BongosClient by
   // /lib/bongos-client.js. baseUrl:'' passes the full same-origin paths this file
   // builds through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
   const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
 
-  const DONE_STATUSES = new Set(['completed', 'confirmed', 'shipped']);
   // task 1888 — the Work tables and the conflicts list render capped; the pager
   // under each expands to the full set.
   const CONFLICT_CAP = 3;
@@ -59,15 +64,6 @@
     todo: makePager('goal-todo', 'otb.goals.todoPerPage'),
     done: makePager('goal-done', 'otb.goals.donePerPage'),
   };
-  // Terminal "deliberately cut" states — neither work-to-do nor done. Excluded
-  // from the todo list and the conflict scan the same way migration 017 keeps
-  // them out of version_progress ("abandoned is a terminal state (deliberately
-  // cut), not pending work"). Without this, an abandoned task shows up under a
-  // goal's "Work to do" as if it were still queued.
-  const CUT_STATUSES = new Set(['abandoned', 'dropped']);
-  // Genuinely-open work under a goal: not done, not cut → {backlog, ready,
-  // active, blocked}.
-  const isTodoStatus = (s) => !DONE_STATUSES.has(s) && !CUT_STATUSES.has(s);
   // Record deep-links (#/task|idea|blocker/N) are owned by the shared overlay
   // (task-detail.js). This page must NOT treat them as a route change (Bug 2).
   const DEEPLINK_RE = /^#\/(?:task|idea|blocker)\/\d+$/;
@@ -148,44 +144,7 @@
     return `<span class="goal-badge ${cls}">${escapeHtml(status)}</span>`;
   }
 
-  function ring(satisfied, total, achieved, size = 42) {
-    const pct = total > 0 ? satisfied / total : (achieved ? 1 : 0);
-    const r = 16;
-    const circ = 2 * Math.PI * r;
-    const dash = (pct * circ).toFixed(1);
-    const gap = (circ - pct * circ).toFixed(1);
-    const stroke = achieved ? 'var(--ok)' : 'var(--accent)';
-    return `<svg class="goal-ring" width="${size}" height="${size}" viewBox="0 0 42 42" role="img" aria-label="${satisfied} of ${total} criteria satisfied">
-        <circle cx="21" cy="21" r="${r}" fill="none" stroke="var(--rule-soft)" stroke-width="4"></circle>
-        <circle cx="21" cy="21" r="${r}" fill="none" stroke="${stroke}" stroke-width="4" stroke-linecap="round" stroke-dasharray="${dash} ${gap}" transform="rotate(-90 21 21)"></circle>
-        <text x="21" y="25" text-anchor="middle" class="goal-ring__label">${satisfied}/${total}</text>
-      </svg>`;
-  }
-
-  function memberName(m) {
-    return m.display_name || (m.github_login ? `@${m.github_login}` : `builder #${m.builder_id}`);
-  }
-
-  // ---- task-readiness rollup (hall redesign task 1002439) --------------------
-  // Dependencies are a TASK property; a goal is only "blocked" in the derived
-  // sense that all its actionable tasks wait on upstream tasks (the Tasks page,
-  // not this one, owns the actual task→task graph). So the Goals page rolls each
-  // goal's tasks into these buckets:
-  //   done     — settled (shipped/confirmed/completed)
-  //   active   — a live claim ("in progress")
-  //   ready    — claimable now (deps met + promoted)
-  //   blocked  — backlog with ≥1 unshipped dependency
-  //   backlog  — backlog, no unmet deps (just not started/promoted)
-  function readinessOf(t) {
-    const s = t.status;
-    if (DONE_STATUSES.has(s)) return 'done';
-    if (CUT_STATUSES.has(s)) return 'cut';
-    if (s === 'active') return 'active';
-    if (s === 'ready') return 'ready';
-    if (s === 'backlog' && (t.blocked_by || []).some((d) => !d.satisfied)) return 'blocked';
-    return 'backlog';
-  }
-  const EMPTY_ROLLUP = { done: 0, active: 0, ready: 0, blocked: 0, backlog: 0, cut: 0, total: 0, nextReady: null };
+  // ring / memberName / readinessOf / EMPTY_ROLLUP → goals-lib.js (task 1003135).
   const rollupOf = (goalId) => state.rollups.get(String(goalId)) || EMPTY_ROLLUP;
 
   // ---- goal ordering (task 1002965) -----------------------------------------
@@ -197,8 +156,6 @@
   //              falling back to the goal row's own updated_at when the goal
   //              has no tasks at all, so a task-less goal still orders sanely
   //              instead of sinking to the bottom forever.
-  const msOf = (iso) => { const t = iso ? Date.parse(iso) : NaN; return Number.isNaN(t) ? 0 : t; };
-  const taskActivityMs = (t) => Math.max(msOf(t.updated_at), msOf(t.shipped_at));
   const goalCreatedMs = (g) => msOf(g.created_at);
   const goalActivityMs = (g) => state.activity.get(String(g.id)) || msOf(g.updated_at);
 
@@ -271,6 +228,40 @@
     }
   }
 
+  // task 1003135 — the Owner dropdown. 'Goal owner' is goals.created_by (the
+  // fixed authority, migration 160), returned by GET /goals as a raw builder id;
+  // labels come from the directory the page already lazily caches (loadDirectory,
+  // task 1877), same label idiom as the invite dropdown. created_by is NULLABLE
+  // (system-attributed — e.g. the migration-160 '<version> — general' catch-alls),
+  // hence the explicit 'system / unattributed' option. Mirrors
+  // populateVersionFilter above; fired after boot's fetch resolves (async because
+  // of the directory fetch — fire-and-forget, the select fills when ready).
+  async function populateOwnerFilter() {
+    const sel = $('#f-goal-owner');
+    if (!sel) return;
+    const ownerIds = Array.from(new Set(
+      state.goals.filter((g) => g.created_by != null).map((g) => String(g.created_by))));
+    const hasSystem = state.goals.some((g) => g.created_by == null);
+    const dir = ownerIds.length ? await loadDirectory() : [];
+    const byId = new Map((dir || []).map((b) => [String(b.id), b]));
+    const label = (id) => {
+      const b = byId.get(id);
+      return b ? (b.display_name || '@' + b.github_login) : `builder #${id}`;
+    };
+    for (const id of ownerIds.sort((a, b) => label(a).localeCompare(label(b)))) {
+      const opt = document.createElement('option');
+      opt.value = id;
+      opt.textContent = label(id);
+      sel.appendChild(opt);
+    }
+    if (hasSystem) {
+      const opt = document.createElement('option');
+      opt.value = 'none';
+      opt.textContent = 'system / unattributed';
+      sel.appendChild(opt);
+    }
+  }
+
   // task 1760 — priority is a WITHIN-version ordering, so the drag affordance
   // only makes sense once the grid is narrowed to exactly one version (the
   // "any" filter mixes versions and dragging across them would be meaningless).
@@ -292,6 +283,18 @@
     const ver = $('#f-goal-version')?.value || '';
     const status = $('#f-goal-status')?.value || '';
     const mineOnly = $('#f-goal-mine')?.value === 'mine';
+    // task 1003135 — free-text search (goal title OR id; '#N', 'N' and a bare
+    // number all match — the id is already rendered on the row, task 1002163)
+    // and the Owner dropdown ('none' = created_by NULL, system-attributed).
+    // Reads the DOM ids directly, matching this function's existing style.
+    const q = ($('#f-goals-search')?.value || '').trim().toLowerCase();
+    const needle = q.replace(/^#/, '');
+    const owner = $('#f-goal-owner')?.value || '';
+    const matchesSearch = (g) => !needle
+      || String(g.id).includes(needle)
+      || (g.title || '').toLowerCase().includes(needle);
+    const matchesOwner = (g) => !owner
+      || (owner === 'none' ? g.created_by == null : String(g.created_by) === owner);
     const myId = selfId();
     const iAmMember = (g) => {
       const d = state.details.get(String(g.id));
@@ -300,22 +303,11 @@
     return state.goals.filter((g) =>
       (!ver || g.version_id === ver) &&
       (!status || g.status === status) &&
+      matchesSearch(g) &&
+      matchesOwner(g) &&
       (!mineOnly || iAmMember(g)));
   }
 
-  // task 1002439 — a goal row's readiness rollup line (only the non-zero buckets).
-  const ROLL_DOTS = [
-    ['ready', 'ready', 'var(--ok)'],
-    ['active', 'in progress', 'var(--info)'],
-    ['blocked', 'blocked', 'var(--terracotta)'],
-    ['backlog', 'backlog', 'var(--ink-faint)'],
-  ];
-  function goalRollLine(r) {
-    const parts = ROLL_DOTS.filter(([k]) => r[k] > 0)
-      .map(([k, label, c]) => `<span class="gr-d"><i style="background:${c}"></i><b>${r[k]}</b> ${label}</span>`);
-    return parts.length ? `<div class="gr-roll">${parts.join('')}</div>` : '';
-  }
-
   // task 1002439 — one goal, rendered as a rollup row: criteria ring · title +
   // meta + readiness rollup · one next action (claim the next ready task, drill
   // into what's blocking, or a review/achieved note).
@@ -515,15 +507,6 @@
     const el = $('#f-goal-search');
     return el ? el.value.trim().toLowerCase() : '';
   }
-  function matchesTodoSearch(t, q) {
-    if (!q) return true;
-    const needle = q.replace(/^#/, '');
-    if (!needle) return true;
-    if (String(t.id).includes(needle)) return true;
-    if ((t.title || '').toLowerCase().includes(needle)) return true;
-    return false;
-  }
-
   // Copy-prompt (work.js:454-503). deHashRefs stops a bare #NNN autolinking to
   // GitHub in a pasted session; the prompt points the builder at the hall task URL.
   async function copyPromptForTask(taskId, btn) {
@@ -1810,6 +1793,9 @@
       const gres = await getJSON(`${API}/goals`);
       state.goals = gres.goals || [];
       populateVersionFilter();
+      // task 1003135 — fire-and-forget: the Owner options fill when the (cached)
+      // directory resolves; boot never waits on a label lookup.
+      populateOwnerFilter().catch(() => {});
       // Prefetch details (ring + members on the cards). Sequentially-parallel,
       // failure-tolerant: a card without detail still renders.
       // task 1002439 — also fold in per-goal task-readiness rollups (one request
@@ -1848,12 +1834,21 @@
   // taken by the goal-detail To-do bar further down this file).
   let savedGoalSort = null;
   try { savedGoalSort = window.localStorage.getItem(GOAL_SORT_PREF); } catch (_) { /* private mode */ }
+  // task 1003135 — Search declared on the kit spec (live 'input' listener comes
+  // free, hall-kit.js:273; no debounce needed, the match is pure client-side over
+  // the already-loaded state.goals). Id is f-goals-search — f-goal-search is
+  // already taken by the goal-detail To-do bar further down this file. Owner
+  // options are filled after boot's fetch (populateOwnerFilter), the
+  // populateVersionFilter pattern. No URL riding (url defaults off here and this
+  // page is deliberately url:false — it owns the #/goal/N hash route).
   makeFilterBar({
     mount: $('#goals-filters'),
+    search: { id: 'f-goals-search', label: 'Search', placeholder: 'goal # or name…' },
     primary: [
       { id: 'f-goal-version', label: 'Version', options: [{ value: '', label: '— any —' }] },
       { id: 'f-goal-status', label: 'Status', options: [{ value: '', label: '— any —' }, 'open', 'achieved', 'archived'] },
       { id: 'f-goal-mine', label: 'Membership', options: [{ value: '', label: 'All goals' }, { value: 'mine', label: 'My goals' }] },
+      { id: 'f-goal-owner', label: 'Owner', options: [{ value: '', label: '— any —' }] },
       { id: 'f-goal-order',
         label: 'Sort',
         value: GOAL_SORTS[savedGoalSort] ? savedGoalSort : undefined,

package/modules/hall-ui/public/goals.html

@@ -198,6 +198,7 @@
 <script src="/builders/task-lib.js"></script>
 <script src="/builders/task-detail.js?v=2026-07-03-taskdetail"></script>
 <script src="/builders/brand-apply.js?v=2026-06-27-r75"></script>
-<script src="/builders/goals-page.js?v=2026-07-10-goals5"></script>
+<script src="/builders/goals-lib.js?v=2026-08-21-goalslib1"></script>
+<script src="/builders/goals-page.js?v=2026-08-21-goals6"></script>
 </body>
 </html>

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.279",
+  "version": "1.19.281",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.279",
+      "version": "1.19.281",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.279",
+  "version": "1.19.281",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/claim.js

@@ -2,7 +2,7 @@
 // Builder claim — atomically claim a task.
 //
 // Usage:
-//   node scripts/gds/claim.js <task-id> [--worktree NAME]
+//   node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join]
 //
 // On success: prints the claim id, the task title, and the touches[] so the
 // builder knows the parallel-safety boundary they're working within.
@@ -165,22 +165,31 @@ function printClaimCard(task, widgetsEnabled = true) {
   } catch (_) { /* never block a claim on the card */ }
 }
 
+// task 1003138: the envelope/flat normalization from formatClaimFailure, pulled
+// out so the goal-join flow reads the same { code, message, d } regardless of
+// response shape. Pure + exported (tested through both consumers).
+function claimErrorInfo(r) {
+  const errRaw = r && r.data ? r.data.error : undefined;
+  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
+  return {
+    code: isEnvelope ? errRaw.code : errRaw,
+    message: isEnvelope ? errRaw.message : undefined,
+    // Structured fields live under .details in the envelope; fall back to the
+    // top-level body for the legacy flat shape (so both keep working).
+    d: { ...(r && r.data ? r.data : {}), ...((isEnvelope && errRaw.details) || {}) },
+  };
+}
+
 // task 1476: render a failed claim as GUIDANCE, not a raw object dump. The API
 // returns the R01 error envelope (ADR 0116): { error: { code, message, details } }.
-// Older paths returned a flat { error: 'CODE', ...fields } shape. This normalizes
-// BOTH — without it `r.data.error` is now an object (never === a string), so every
-// branch below silently missed and the refusal printed as `[object Object]`. Pure
-// (no console / no process.exit) + exported so it can be unit-tested against the
-// real envelope shapes. Returns { lines, exit }.
+// Older paths returned a flat { error: 'CODE', ...fields } shape. claimErrorInfo
+// normalizes BOTH — without it `r.data.error` is now an object (never === a
+// string), so every branch below silently missed and the refusal printed as
+// `[object Object]`. Pure (no console / no process.exit) + exported so it can be
+// unit-tested against the real envelope shapes. Returns { lines, exit }.
 function formatClaimFailure(r, taskId) {
   const lines = [];
-  const errRaw = r && r.data ? r.data.error : undefined;
-  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
-  const code = isEnvelope ? errRaw.code : errRaw;
-  const message = isEnvelope ? errRaw.message : undefined;
-  // Structured fields live under .details in the envelope; fall back to the
-  // top-level body for the legacy flat shape (so both keep working).
-  const d = { ...(r && r.data ? r.data : {}), ...((isEnvelope && errRaw.details) || {}) };
+  const { code, message, d } = claimErrorInfo(r);
 
   // #766: a generic onboarding stage gate (kept rendering cleanly, not as raw JSON).
   if (code === 'stage_required') {
@@ -263,17 +272,147 @@ function formatClaimFailure(r, taskId) {
     lines.push('Resolve it first (/blocker-solve N drives one to done; resolving auto-promotes its linked tasks) — or pick another task from /builder-start.');
     return { lines, exit: 1 };
   }
+  if (code === 'GOAL_MEMBERSHIP_REQUIRED') {
+    // task 1003138: the non-interactive rendering of the membership refusal —
+    // the interactive offer (runGoalJoinFlow) normally intercepts this code
+    // before it gets here; this branch covers a retry that re-refused, an
+    // unexpected body, or a decline.
+    lines.push(`Task #${taskId} lives in goal ${d.goal_id}${d.goal_title ? ` ("${d.goal_title}")` : ''}${d.visibility ? ` (${d.visibility})` : ''} — you are not a member.`);
+    lines.push(d.action === 'apply'
+      ? `  Apply to join (POST /api/bongos/goals/${d.goal_id}/requests) — nothing can be claimed until an owner approves. Re-run with --join to file the application from here.`
+      : `  Join and claim in one command:  node scripts/gds/claim.js ${taskId} --join`);
+    return { lines, exit: 1 };
+  }
   // Fallback — still readable: the message + code, never a raw [object Object].
   lines.push(`Claim failed (${r ? r.status : '?'})${code ? ` [${code}]` : ''}${message ? `: ${message}` : ''}.`);
   return { lines, exit: 1 };
 }
 
+// task 1003138 (owner ask, verbatim: 'claude should offer to join so they dont
+// need to go through the ui') — the goal-membership refusal (403
+// GOAL_MEMBERSHIP_REQUIRED, the task-1003137 gate) is resolvable in-session.
+// goalMembershipOfferPlan is the PURE half: given the refusal details it names
+// the offer to make. Exported for unit tests; the I/O lives in runGoalJoinFlow.
+// Returns null when the body is missing the fields the flow needs (falls back
+// to formatClaimFailure), else { action, headerLines, question }.
+function goalMembershipOfferPlan(d, taskId) {
+  if (!d || d.goal_id == null || (d.action !== 'join' && d.action !== 'apply')) return null;
+  const g = d.goal_id;
+  if (d.action === 'join') {
+    return {
+      action: 'join',
+      headerLines: [
+        `✗ Task ${taskId} lives in goal ${g}`,
+        ...(d.goal_title ? [`    "${d.goal_title}" (${d.visibility || 'public'})`] : []),
+        '    You are not a member.',
+      ],
+      question: `Join goal ${g} and claim? [Y/n] `,
+    };
+  }
+  // 'apply' — a private goal, or a public one whose scope is Archon-mediated
+  // (the server folds both to apply; a pending request grants nothing yet).
+  return {
+    action: 'apply',
+    headerLines: d.visibility === 'private'
+      ? [`✗ Goal ${g} is private.`]
+      : [
+        `✗ Task ${taskId} lives in goal ${g}${d.goal_title ? ` ("${d.goal_title}")` : ''} — joining needs approval (Archon-mediated scope).`,
+      ],
+    question: 'Apply to join? [Y/n] ',
+  };
+}
+
+// One yes/no on the real terminal (default yes — the owner-approved [Y/n]
+// shape). Returns null when there is no TTY to ask — the caller then prints
+// the --join re-run hint instead of hanging a non-interactive session.
+async function promptYesNo(question) {
+  if (!process.stdin.isTTY) return null;
+  const readline = require('node:readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const a = (await rl.question(question)).trim().toLowerCase();
+    return a === '' || a === 'y' || a === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+// The I/O half of the offer. Outcomes: 'retry' (joined — re-POST the claim),
+// 'stop' (declined / filed / blocked — everything already printed, exit 1),
+// 'unhandled' (fall through to formatClaimFailure). Never joins or files
+// without a yes: --join is the standing yes for non-interactive sessions.
+async function runGoalJoinFlow({ api, d, taskId, assumeYes }) {
+  const plan = goalMembershipOfferPlan(d, taskId);
+  if (!plan) return 'unhandled';
+  const goalId = d.goal_id;
+  for (const line of plan.headerLines) console.error(line);
+
+  const yes = assumeYes ? true : await promptYesNo(plan.question);
+  if (yes === null) {
+    // Non-interactive (an agent session): make the one-command path explicit.
+    console.error(plan.action === 'join'
+      ? `  To join goal ${goalId} and claim in one command:  node scripts/gds/claim.js ${taskId} --join`
+      : `  To file the application from here:  node scripts/gds/claim.js ${taskId} --join   (nothing claimable until approved)`);
+    return 'stop';
+  }
+  if (!yes) {
+    // The owner chose the explicit-join model — declining leaves NO membership
+    // row and NO request.
+    console.error(plan.action === 'join'
+      ? '  Declined — nothing joined, nothing claimed.'
+      : '  Declined — no application filed, nothing claimed.');
+    return 'stop';
+  }
+
+  if (plan.action === 'join') {
+    const jr = await api.goals.postGoalsIdJoin({ id: goalId, body: {} });
+    if (jr.status === 200 || jr.status === 201) {
+      console.error(`+ joined goal ${goalId} (member)`);
+      return 'retry';
+    }
+    const j = claimErrorInfo(jr);
+    if (j.code === 'archon_approval_required') {
+      // The third branch, handled honestly (routes/goals.js:615): a PUBLIC goal
+      // with protected scope is not self-joinable — don't loop, name the path.
+      console.error(`✗ Goal ${goalId}'s scope is Archon-mediated — self-join is not allowed.`);
+      console.error(`  Request to join instead:  node scripts/gds/claim.js ${taskId} --join  (after the server re-offers apply), or ask an Archon to add you.`);
+      return 'stop';
+    }
+    if (j.code === 'goal_private') {
+      // Visibility flipped between refusal and join — report, don't loop.
+      console.error(`✗ Goal ${goalId} is private now — request to join (POST /api/bongos/goals/${goalId}/requests) and wait for approval.`);
+      return 'stop';
+    }
+    console.error(`✗ join failed (${jr.status})${j.code ? ` [${j.code}]` : ''}${j.message ? `: ${j.message}` : ''}.`);
+    return 'stop';
+  }
+
+  // 'apply' — file the request; a pending row grants nothing, so never retry
+  // the claim here.
+  const ar = await api.goals.postGoalsIdRequests({ id: goalId, body: {} });
+  if (ar.status === 201) {
+    console.error('+ request filed — pending owner approval');
+    console.error('  (nothing to claim until approved)');
+    return 'stop';
+  }
+  const a = claimErrorInfo(ar);
+  if (a.code === 'request_pending') {
+    // The core_188 partial-unique: one pending ask per goal per builder —
+    // re-running reports, it does not error.
+    console.error('• already pending — your earlier request for this goal awaits owner approval.');
+    console.error('  (nothing to claim until approved)');
+    return 'stop';
+  }
+  console.error(`✗ application failed (${ar.status})${a.code ? ` [${a.code}]` : ''}${a.message ? `: ${a.message}` : ''}.`);
+  return 'stop';
+}
+
 async function main() {
   await requireSession();
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches]');
+    console.error('usage: node scripts/gds/claim.js <task-id> [--worktree NAME] [--enforce-touches] [--join]');
     process.exit(2);
   }
   const wIdx = args.indexOf('--worktree');
@@ -287,10 +426,15 @@ async function main() {
   // --enforce-touches so adjacency becomes a HARD refusal (it fans concurrent
   // unsupervised agents that could clobber each other on shared files).
   const enforceTouches = args.includes('--enforce-touches');
+  // task 1003138: --join is the standing yes to the goal-membership offer —
+  // join (public) or file the application (private/protected) and, for a join,
+  // retry the claim, all in one command. Without it an interactive session is
+  // asked [Y/n]; a non-TTY session is shown the --join re-run line.
+  const assumeYes = args.includes('--join');
   const headSha = captureHeadSha();
 
   const api = await cliClient();
-  const r = await api.claims.postClaims({
+  const postClaim = () => api.claims.postClaims({
     body: {
       task_id: taskId,
       worktree_name: worktree,
@@ -298,6 +442,19 @@ async function main() {
       enforce_touches: enforceTouches,
     },
   });
+  let r = await postClaim();
+  // task 1003138: a goal-membership refusal (the task-1003137 gate) is
+  // resolvable in-session — offer the join/application, and on a successful
+  // join retry the claim ONCE (a second refusal falls through to the plain
+  // rendering; never loop).
+  if (r.status !== 201 && claimErrorInfo(r).code === 'GOAL_MEMBERSHIP_REQUIRED') {
+    const outcome = await runGoalJoinFlow({ api, d: claimErrorInfo(r).d, taskId, assumeYes });
+    if (outcome === 'retry') {
+      r = await postClaim();
+    } else if (outcome === 'stop') {
+      process.exit(1); // everything already printed; no claim landed
+    }
+  }
   if (r.status === 201) {
     const { claim, task } = r.data;
     console.log(`Claimed task #${task.id}: ${task.title}`);
@@ -433,4 +590,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { formatClaimFailure };
+module.exports = { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan };

package/src/module-api.js

@@ -985,8 +985,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.277 with no explicit bump. run 32508270995. (task 1002620)
 //   1.19.279 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.278 with no explicit bump. run 32521664476. (task 1002620)
+//   1.19.280 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.279 with no explicit bump. run 32523185119. (task 1002620)
+//   1.19.281 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.280 with no explicit bump. run 32525071763. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.279'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.281'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');