terminalhire 0.40.3 → 0.40.4

package/dist/bin/claim-push-bg.js

@@ -90,6 +90,7 @@ var init_state_dir = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -288,7 +289,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR3, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR3, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -299,6 +300,22 @@ var init_claims = __esm({
     LOCK_STALE_MS = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",

package/dist/bin/jpi-bounties.js

@@ -11122,6 +11122,7 @@ var init_repo_experience = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -11320,7 +11321,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR5, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR5, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -11331,6 +11332,22 @@ var init_claims = __esm({
     LOCK_STALE_MS = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",

package/dist/bin/jpi-claim.js

@@ -10431,6 +10431,7 @@ var init_state_dir = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -10629,7 +10630,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR2, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR2, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -10640,6 +10641,22 @@ var init_claims = __esm({
     LOCK_STALE_MS = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",
@@ -26705,6 +26722,38 @@ function printMetric(rate) {
   console.log(`
 \u{1F4CA} Accepted-PR rate: ${rate.merged}/${rate.total} claims merged (${pct}%)`);
 }
+var SUBMIT_ACCEPTS = Object.freeze(["working", "ready"]);
+function nextStepFor(c) {
+  const founder = Boolean(c.approval);
+  switch (c.state) {
+    case "claimed":
+      return founder ? { cmd: `terminalhire claim slice ${c.id}`, why: "collect your granted work slice" } : { cmd: `terminalhire claim start ${c.id}`, why: "fork + clone into a worktree" };
+    // NOT grouped with the two below. `cmdSubmit` accepts 'working' and 'ready'
+    // and nothing else, so pointing an 'in-review' claim at submit would hand the
+    // developer a command that exits 1 — and submit's own refusal then advises
+    // `claim start`, which a founder claim can never use either. Two dead ends in
+    // a row is worse than the silence this block replaced.
+    case "in-review":
+      return {
+        cmd: `terminalhire claim update ${c.id} ready`,
+        why: "clear the review gate \u2014 submit only accepts working/ready"
+      };
+    case "working":
+    case "ready":
+      return { cmd: `terminalhire claim submit ${c.id}`, why: "push the branch + open the PR" };
+    case "submitted":
+      return founder ? { cmd: `terminalhire claim runs ${c.id} --watch`, why: "read the CI result" } : { cmd: `terminalhire claim status ${c.id}`, why: "poll the PR merge state" };
+    default:
+      return null;
+  }
+}
+function printNextSteps(list) {
+  const steps = list.map(nextStepFor).filter(Boolean);
+  if (steps.length === 0) return;
+  const width = Math.max(...steps.map((s) => s.cmd.length));
+  console.log("\n  Next:");
+  for (const s of steps) console.log(`    ${s.cmd.padEnd(width)}   \u2014 ${s.why}`);
+}
 async function resolveBounty(arg) {
   let bountyId, title, repoFullName, issueUrl, amountUSD, source, openPRsAtDiscovery, indexNativeId;
   let founderPosting = false;
@@ -27276,6 +27325,7 @@ ${list.length} ${active ? "active " : ""}claim${list.length === 1 ? "" : "s"}:
     console.log(`    id: ${c.id}${pr}`);
   }
   printMetric(claims.acceptedPRRate());
+  printNextSteps(list);
   try {
     if (await shouldNudgeUnpushed()) {
       console.log(
@@ -27424,7 +27474,7 @@ async function cmdStatus(id) {
 }
 async function cmdUpdate(id, state, prUrl) {
   const claims = await Promise.resolve().then(() => (init_claims(), claims_exports));
-  const VALID = ["claimed", "working", "in-review", "ready", "submitted", "merged", "abandoned"];
+  const VALID = claims.CLAIM_STATES;
   if (!id || !state || !VALID.includes(state)) {
     console.error("Usage: terminalhire claim update <id> <state> [prUrl]");
     console.error("  state: " + VALID.join(" | "));
@@ -28284,7 +28334,7 @@ async function cmdSubmit(id, flags = {}) {
     console.error(`terminalhire claim: no claim with id '${id}'.`);
     process.exit(1);
   }
-  if (claim.state !== "working" && claim.state !== "ready") {
+  if (!SUBMIT_ACCEPTS.includes(claim.state)) {
     console.error(
       `terminalhire claim: ${id} is '${claim.state}'. Submit runs once work has started ('working', via 'claim start') or the review gate cleared it ('ready'). Start it first:
   terminalhire claim start ${id}`
@@ -29236,6 +29286,7 @@ async function run() {
 export {
   AI_DISCLOSURE_NOTE,
   CLAIM_CONSENT_VERSION,
+  SUBMIT_ACCEPTS,
   backgroundEnableFailed,
   buildAssignmentComment,
   buildPatchSubmission,
@@ -29261,9 +29312,11 @@ export {
   listMergedPRsReferencingIssue,
   listOpenPRsReferencingIssue,
   matchReferencingPrs,
+  nextStepFor,
   normalizeIntent,
   pickBodySource,
   pickExistingPr,
+  printNextSteps,
   renderRunView,
   renderServerRefusal,
   resolveBounty,

package/dist/bin/jpi-contribute.js

@@ -3515,6 +3515,7 @@ var init_repo_experience = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -3713,7 +3714,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR7, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR7, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -3724,6 +3725,22 @@ var init_claims = __esm({
     LOCK_STALE_MS = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",

package/dist/bin/jpi-dispatch.js

@@ -14859,6 +14859,7 @@ var init_repo_experience = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -15057,7 +15058,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR11, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS2, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR11, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS2, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -15068,6 +15069,22 @@ var init_claims = __esm({
     LOCK_STALE_MS2 = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",
@@ -30462,6 +30479,7 @@ var jpi_claim_exports = {};
 __export(jpi_claim_exports, {
   AI_DISCLOSURE_NOTE: () => AI_DISCLOSURE_NOTE,
   CLAIM_CONSENT_VERSION: () => CLAIM_CONSENT_VERSION,
+  SUBMIT_ACCEPTS: () => SUBMIT_ACCEPTS,
   backgroundEnableFailed: () => backgroundEnableFailed,
   buildAssignmentComment: () => buildAssignmentComment,
   buildPatchSubmission: () => buildPatchSubmission,
@@ -30487,9 +30505,11 @@ __export(jpi_claim_exports, {
   listMergedPRsReferencingIssue: () => listMergedPRsReferencingIssue,
   listOpenPRsReferencingIssue: () => listOpenPRsReferencingIssue,
   matchReferencingPrs: () => matchReferencingPrs,
+  nextStepFor: () => nextStepFor,
   normalizeIntent: () => normalizeIntent,
   pickBodySource: () => pickBodySource,
   pickExistingPr: () => pickExistingPr,
+  printNextSteps: () => printNextSteps,
   renderRunView: () => renderRunView,
   renderServerRefusal: () => renderServerRefusal,
   resolveBounty: () => resolveBounty,
@@ -31166,6 +31186,37 @@ function printMetric(rate) {
   console.log(`
 \u{1F4CA} Accepted-PR rate: ${rate.merged}/${rate.total} claims merged (${pct2}%)`);
 }
+function nextStepFor(c) {
+  const founder = Boolean(c.approval);
+  switch (c.state) {
+    case "claimed":
+      return founder ? { cmd: `terminalhire claim slice ${c.id}`, why: "collect your granted work slice" } : { cmd: `terminalhire claim start ${c.id}`, why: "fork + clone into a worktree" };
+    // NOT grouped with the two below. `cmdSubmit` accepts 'working' and 'ready'
+    // and nothing else, so pointing an 'in-review' claim at submit would hand the
+    // developer a command that exits 1 — and submit's own refusal then advises
+    // `claim start`, which a founder claim can never use either. Two dead ends in
+    // a row is worse than the silence this block replaced.
+    case "in-review":
+      return {
+        cmd: `terminalhire claim update ${c.id} ready`,
+        why: "clear the review gate \u2014 submit only accepts working/ready"
+      };
+    case "working":
+    case "ready":
+      return { cmd: `terminalhire claim submit ${c.id}`, why: "push the branch + open the PR" };
+    case "submitted":
+      return founder ? { cmd: `terminalhire claim runs ${c.id} --watch`, why: "read the CI result" } : { cmd: `terminalhire claim status ${c.id}`, why: "poll the PR merge state" };
+    default:
+      return null;
+  }
+}
+function printNextSteps(list) {
+  const steps = list.map(nextStepFor).filter(Boolean);
+  if (steps.length === 0) return;
+  const width = Math.max(...steps.map((s) => s.cmd.length));
+  console.log("\n  Next:");
+  for (const s of steps) console.log(`    ${s.cmd.padEnd(width)}   \u2014 ${s.why}`);
+}
 async function resolveBounty(arg) {
   let bountyId, title, repoFullName, issueUrl, amountUSD, source, openPRsAtDiscovery, indexNativeId;
   let founderPosting = false;
@@ -31737,6 +31788,7 @@ ${list.length} ${active ? "active " : ""}claim${list.length === 1 ? "" : "s"}:
     console.log(`    id: ${c.id}${pr}`);
   }
   printMetric(claims.acceptedPRRate());
+  printNextSteps(list);
   try {
     if (await shouldNudgeUnpushed()) {
       console.log(
@@ -31884,7 +31936,7 @@ async function cmdStatus(id) {
 }
 async function cmdUpdate(id, state, prUrl) {
   const claims = await Promise.resolve().then(() => (init_claims(), claims_exports));
-  const VALID = ["claimed", "working", "in-review", "ready", "submitted", "merged", "abandoned"];
+  const VALID = claims.CLAIM_STATES;
   if (!id || !state || !VALID.includes(state)) {
     console.error("Usage: terminalhire claim update <id> <state> [prUrl]");
     console.error("  state: " + VALID.join(" | "));
@@ -32742,7 +32794,7 @@ async function cmdSubmit(id, flags = {}) {
     console.error(`terminalhire claim: no claim with id '${id}'.`);
     process.exit(1);
   }
-  if (claim.state !== "working" && claim.state !== "ready") {
+  if (!SUBMIT_ACCEPTS.includes(claim.state)) {
     console.error(
       `terminalhire claim: ${id} is '${claim.state}'. Submit runs once work has started ('working', via 'claim start') or the review gate cleared it ('ready'). Start it first:
   terminalhire claim start ${id}`
@@ -33691,7 +33743,7 @@ async function run7() {
     process.exit(1);
   }
 }
-var TERMINALHIRE_DIR17, INDEX_CACHE_FILE5, CLAIM_PUSH_MARKER, REPO_CONTINUITY_NUDGE_MARKER, API_URL6, CLAIM_SYNC_BASE2, CLAIM_CONSENT_VERSION, CLAIM_POLL_INTERVAL_MS, CLAIM_POLL_TIMEOUT_MS, GH_API3, GH_HEADERS2, CONTENTION_HINT, AI_DISCLOSURE_NOTE, pExecFile, VALUE_FLAGS, ASSIGNMENT_MARKER, STAKE_MARKER, STANDDOWN_MARKER, OUR_MARKERS, STAKE_POST_TIMEOUT_MS, STAKE_POSTING_GRACE_MS, TAKE_BOT_REPOS, ISSUE_OUTCOME_TERMINAL, RUNS_POLL_INTERVAL_MS, RUNS_POLL_ATTEMPTS;
+var TERMINALHIRE_DIR17, INDEX_CACHE_FILE5, CLAIM_PUSH_MARKER, REPO_CONTINUITY_NUDGE_MARKER, API_URL6, CLAIM_SYNC_BASE2, CLAIM_CONSENT_VERSION, CLAIM_POLL_INTERVAL_MS, CLAIM_POLL_TIMEOUT_MS, GH_API3, GH_HEADERS2, CONTENTION_HINT, AI_DISCLOSURE_NOTE, pExecFile, VALUE_FLAGS, ASSIGNMENT_MARKER, STAKE_MARKER, STANDDOWN_MARKER, OUR_MARKERS, STAKE_POST_TIMEOUT_MS, STAKE_POSTING_GRACE_MS, TAKE_BOT_REPOS, SUBMIT_ACCEPTS, ISSUE_OUTCOME_TERMINAL, RUNS_POLL_INTERVAL_MS, RUNS_POLL_ATTEMPTS;
 var init_jpi_claim = __esm({
   "bin/jpi-claim.js"() {
     "use strict";
@@ -33723,6 +33775,7 @@ var init_jpi_claim = __esm({
     STAKE_POST_TIMEOUT_MS = 3e4;
     STAKE_POSTING_GRACE_MS = STAKE_POST_TIMEOUT_MS + 15e3;
     TAKE_BOT_REPOS = /* @__PURE__ */ new Set(["paradedb/paradedb"]);
+    SUBMIT_ACCEPTS = Object.freeze(["working", "ready"]);
     ISSUE_OUTCOME_TERMINAL = /* @__PURE__ */ new Set(["own-merge", "other-merge", "closed-unmerged"]);
     RUNS_POLL_INTERVAL_MS = 15e3;
     RUNS_POLL_ATTEMPTS = 20;

package/dist/bin/jpi-hub.js

@@ -462,6 +462,7 @@ var init_state_dir = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -660,7 +661,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -671,6 +672,22 @@ var init_claims = __esm({
     LOCK_STALE_MS = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",

package/dist/bin/jpi-mcp.js

@@ -10903,6 +10903,7 @@ var init_policy_acks = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -11101,7 +11102,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR5, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR5, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -11112,6 +11113,22 @@ var init_claims = __esm({
     LOCK_STALE_MS = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",
@@ -26046,6 +26063,7 @@ var jpi_claim_exports = {};
 __export(jpi_claim_exports, {
   AI_DISCLOSURE_NOTE: () => AI_DISCLOSURE_NOTE,
   CLAIM_CONSENT_VERSION: () => CLAIM_CONSENT_VERSION,
+  SUBMIT_ACCEPTS: () => SUBMIT_ACCEPTS,
   backgroundEnableFailed: () => backgroundEnableFailed,
   buildAssignmentComment: () => buildAssignmentComment,
   buildPatchSubmission: () => buildPatchSubmission,
@@ -26071,9 +26089,11 @@ __export(jpi_claim_exports, {
   listMergedPRsReferencingIssue: () => listMergedPRsReferencingIssue,
   listOpenPRsReferencingIssue: () => listOpenPRsReferencingIssue,
   matchReferencingPrs: () => matchReferencingPrs,
+  nextStepFor: () => nextStepFor,
   normalizeIntent: () => normalizeIntent,
   pickBodySource: () => pickBodySource,
   pickExistingPr: () => pickExistingPr,
+  printNextSteps: () => printNextSteps,
   renderRunView: () => renderRunView,
   renderServerRefusal: () => renderServerRefusal,
   resolveBounty: () => resolveBounty,
@@ -26750,6 +26770,37 @@ function printMetric(rate) {
   console.log(`
 \u{1F4CA} Accepted-PR rate: ${rate.merged}/${rate.total} claims merged (${pct}%)`);
 }
+function nextStepFor(c) {
+  const founder = Boolean(c.approval);
+  switch (c.state) {
+    case "claimed":
+      return founder ? { cmd: `terminalhire claim slice ${c.id}`, why: "collect your granted work slice" } : { cmd: `terminalhire claim start ${c.id}`, why: "fork + clone into a worktree" };
+    // NOT grouped with the two below. `cmdSubmit` accepts 'working' and 'ready'
+    // and nothing else, so pointing an 'in-review' claim at submit would hand the
+    // developer a command that exits 1 — and submit's own refusal then advises
+    // `claim start`, which a founder claim can never use either. Two dead ends in
+    // a row is worse than the silence this block replaced.
+    case "in-review":
+      return {
+        cmd: `terminalhire claim update ${c.id} ready`,
+        why: "clear the review gate \u2014 submit only accepts working/ready"
+      };
+    case "working":
+    case "ready":
+      return { cmd: `terminalhire claim submit ${c.id}`, why: "push the branch + open the PR" };
+    case "submitted":
+      return founder ? { cmd: `terminalhire claim runs ${c.id} --watch`, why: "read the CI result" } : { cmd: `terminalhire claim status ${c.id}`, why: "poll the PR merge state" };
+    default:
+      return null;
+  }
+}
+function printNextSteps(list) {
+  const steps = list.map(nextStepFor).filter(Boolean);
+  if (steps.length === 0) return;
+  const width = Math.max(...steps.map((s) => s.cmd.length));
+  console.log("\n  Next:");
+  for (const s of steps) console.log(`    ${s.cmd.padEnd(width)}   \u2014 ${s.why}`);
+}
 async function resolveBounty(arg) {
   let bountyId, title, repoFullName, issueUrl, amountUSD, source, openPRsAtDiscovery, indexNativeId;
   let founderPosting = false;
@@ -27321,6 +27372,7 @@ ${list.length} ${active ? "active " : ""}claim${list.length === 1 ? "" : "s"}:
     console.log(`    id: ${c.id}${pr}`);
   }
   printMetric(claims.acceptedPRRate());
+  printNextSteps(list);
   try {
     if (await shouldNudgeUnpushed()) {
       console.log(
@@ -27468,7 +27520,7 @@ async function cmdStatus(id) {
 }
 async function cmdUpdate(id, state, prUrl) {
   const claims = await Promise.resolve().then(() => (init_claims(), claims_exports));
-  const VALID = ["claimed", "working", "in-review", "ready", "submitted", "merged", "abandoned"];
+  const VALID = claims.CLAIM_STATES;
   if (!id || !state || !VALID.includes(state)) {
     console.error("Usage: terminalhire claim update <id> <state> [prUrl]");
     console.error("  state: " + VALID.join(" | "));
@@ -28326,7 +28378,7 @@ async function cmdSubmit(id, flags = {}) {
     console.error(`terminalhire claim: no claim with id '${id}'.`);
     process.exit(1);
   }
-  if (claim.state !== "working" && claim.state !== "ready") {
+  if (!SUBMIT_ACCEPTS.includes(claim.state)) {
     console.error(
       `terminalhire claim: ${id} is '${claim.state}'. Submit runs once work has started ('working', via 'claim start') or the review gate cleared it ('ready'). Start it first:
   terminalhire claim start ${id}`
@@ -29275,7 +29327,7 @@ async function run() {
     process.exit(1);
   }
 }
-var TERMINALHIRE_DIR11, INDEX_CACHE_FILE2, CLAIM_PUSH_MARKER, REPO_CONTINUITY_NUDGE_MARKER, API_URL, CLAIM_SYNC_BASE, CLAIM_CONSENT_VERSION, CLAIM_POLL_INTERVAL_MS, CLAIM_POLL_TIMEOUT_MS, GH_API2, GH_HEADERS2, CONTENTION_HINT, AI_DISCLOSURE_NOTE, pExecFile, VALUE_FLAGS, ASSIGNMENT_MARKER, STAKE_MARKER, STANDDOWN_MARKER, OUR_MARKERS, STAKE_POST_TIMEOUT_MS, STAKE_POSTING_GRACE_MS, TAKE_BOT_REPOS, ISSUE_OUTCOME_TERMINAL, RUNS_POLL_INTERVAL_MS, RUNS_POLL_ATTEMPTS;
+var TERMINALHIRE_DIR11, INDEX_CACHE_FILE2, CLAIM_PUSH_MARKER, REPO_CONTINUITY_NUDGE_MARKER, API_URL, CLAIM_SYNC_BASE, CLAIM_CONSENT_VERSION, CLAIM_POLL_INTERVAL_MS, CLAIM_POLL_TIMEOUT_MS, GH_API2, GH_HEADERS2, CONTENTION_HINT, AI_DISCLOSURE_NOTE, pExecFile, VALUE_FLAGS, ASSIGNMENT_MARKER, STAKE_MARKER, STANDDOWN_MARKER, OUR_MARKERS, STAKE_POST_TIMEOUT_MS, STAKE_POSTING_GRACE_MS, TAKE_BOT_REPOS, SUBMIT_ACCEPTS, ISSUE_OUTCOME_TERMINAL, RUNS_POLL_INTERVAL_MS, RUNS_POLL_ATTEMPTS;
 var init_jpi_claim = __esm({
   "bin/jpi-claim.js"() {
     "use strict";
@@ -29307,6 +29359,7 @@ var init_jpi_claim = __esm({
     STAKE_POST_TIMEOUT_MS = 3e4;
     STAKE_POSTING_GRACE_MS = STAKE_POST_TIMEOUT_MS + 15e3;
     TAKE_BOT_REPOS = /* @__PURE__ */ new Set(["paradedb/paradedb"]);
+    SUBMIT_ACCEPTS = Object.freeze(["working", "ready"]);
     ISSUE_OUTCOME_TERMINAL = /* @__PURE__ */ new Set(["own-merge", "other-merge", "closed-unmerged"]);
     RUNS_POLL_INTERVAL_MS = 15e3;
     RUNS_POLL_ATTEMPTS = 20;

package/dist/bin/jpi-refresh.js

@@ -12283,6 +12283,7 @@ var init_github_auth = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -12481,7 +12482,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR8, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS2, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR8, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS2, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -12492,6 +12493,22 @@ var init_claims = __esm({
     LOCK_STALE_MS2 = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",

package/dist/bin/jpi-repo.js

@@ -1824,6 +1824,7 @@ var init_repo_experience = __esm({
 // src/claims.ts
 var claims_exports = {};
 __export(claims_exports, {
+  CLAIM_STATES: () => CLAIM_STATES,
   PUSHED_CLAIM_FIELDS: () => PUSHED_CLAIM_FIELDS,
   acceptedPRRate: () => acceptedPRRate,
   countAwaitingFounderApproval: () => countAwaitingFounderApproval,
@@ -2022,7 +2023,7 @@ function acceptedPRRate(claims = readClaims()) {
   const merged = claims.filter((c) => c.state === "merged").length;
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
-var TERMINALHIRE_DIR4, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
+var TERMINALHIRE_DIR4, CLAIMS_FILE, LOCK_DIR, LOCK_STALE_MS, LOCK_RETRY_MS, LOCK_TIMEOUT_MS, CLAIM_STATES, PUSHED_CLAIM_FIELDS, TERMINAL_STATES, POLL_TRANSITIONS;
 var init_claims = __esm({
   "src/claims.ts"() {
     "use strict";
@@ -2033,6 +2034,22 @@ var init_claims = __esm({
     LOCK_STALE_MS = Number(process.env.TERMINALHIRE_LOCK_STALE_MS) || 1e4;
     LOCK_RETRY_MS = Number(process.env.TERMINALHIRE_LOCK_RETRY_MS) || 25;
     LOCK_TIMEOUT_MS = Number(process.env.TERMINALHIRE_LOCK_TIMEOUT_MS) || 5e3;
+    CLAIM_STATES = Object.freeze([
+      "claimed",
+      // recorded, not started
+      "working",
+      // background executor running / work in progress
+      "in-review",
+      // gate ran / dev reviewing the diff
+      "ready",
+      // passed review, cleared to submit
+      "submitted",
+      // PR opened on the source platform (awaiting maintainer)
+      "merged",
+      // PR merged — accepted; counts toward the metric
+      "abandoned"
+      // released, or PR closed unmerged
+    ]);
     PUSHED_CLAIM_FIELDS = [
       "kind",
       "repoFullName",

package/dist/src/claims.js

@@ -99,6 +99,22 @@ function withClaimsLock(fn) {
     rmSync(LOCK_DIR, { recursive: true, force: true });
   }
 }
+var CLAIM_STATES = Object.freeze([
+  "claimed",
+  // recorded, not started
+  "working",
+  // background executor running / work in progress
+  "in-review",
+  // gate ran / dev reviewing the diff
+  "ready",
+  // passed review, cleared to submit
+  "submitted",
+  // PR opened on the source platform (awaiting maintainer)
+  "merged",
+  // PR merged — accepted; counts toward the metric
+  "abandoned"
+  // released, or PR closed unmerged
+]);
 var PUSHED_CLAIM_FIELDS = [
   "kind",
   "repoFullName",
@@ -269,6 +285,7 @@ function acceptedPRRate(claims = readClaims()) {
   return { merged, total, rate: total === 0 ? 0 : merged / total };
 }
 export {
+  CLAIM_STATES,
   PUSHED_CLAIM_FIELDS,
   acceptedPRRate,
   countAwaitingFounderApproval,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminalhire",
-  "version": "0.40.3",
+  "version": "0.40.4",
   "description": "Local-first job matching for developers — ambient job matches in the Claude Code spinner. Your profile never leaves your machine.",
   "repository": {
     "type": "git",