terminalhire 0.42.14 → 0.42.15

package/dist/bin/jpi-claim.js

@@ -28054,6 +28054,9 @@ function labelSelector(labels) {
     throw new EnvRunError("labels object is empty; pass at least one label or omit it");
   return `${first[0]}=${first[1]}`;
 }
+function withUserScriptPath(command) {
+  return `PATH="$PATH:$HOME/.local/bin"; export PATH; ${command}`;
+}
 async function runStep(containment, r) {
   const spec = {
     profile: r.profile,
@@ -28068,7 +28071,7 @@ async function runStep(containment, r) {
     pathDomain: r.pathDomain,
     guestUser: r.guestUser,
     program: "/bin/sh",
-    args: ["-c", r.command]
+    args: ["-c", withUserScriptPath(r.command)]
   };
   const startedAt = Date.now();
   const res = await containment.run(spec, r.env, {
@@ -35295,6 +35298,42 @@ function printNextSteps(list) {
     console.log(`    ${s.cmd.padEnd(width)}   \u2014 ${s.why}`);
   }
 }
+async function explainUnresolvable(arg) {
+  const generic = [
+    `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`,
+    "  Run `terminalhire bounties` to populate the cache, or pass a full issue URL."
+  ];
+  if (!looksLikeShortRef(arg)) return generic;
+  try {
+    const { readClaims: readClaims2 } = await Promise.resolve().then(() => (init_claims(), claims_exports));
+    const mine = readClaims2().find((c) => c?.id && opportunityShortToken(c.id) === arg);
+    if (mine) {
+      return [
+        `terminalhire claim: you have already claimed '${arg}'.`,
+        `  ${mine.title ?? mine.id}`,
+        "  A claimed posting leaves the public index, so it cannot be claimed again.",
+        "",
+        `  Get your workspace:   terminalhire claim start ${mine.id}`,
+        `  See where it stands:  terminalhire claim status ${mine.id}`
+      ];
+    }
+  } catch {
+  }
+  return [
+    `terminalhire claim: '${arg}' did not resolve to anything you can claim.`,
+    "  It has the shape of a claim token, so one of two things is true, and this",
+    "  command cannot tell them apart:",
+    "",
+    "    \u2022 the posting was claimed or withdrawn. A claimed posting leaves the",
+    "      public index, and `terminalhire bounties` will never bring it back.",
+    "    \u2022 the token is unknown here \u2014 mistyped, or minted against a different",
+    "      environment than the one this command is pointed at.",
+    "",
+    `  Open it:            ${API_URL}/c/${arg}`,
+    "  Already yours?      terminalhire claim list",
+    "  Refresh the index:  terminalhire bounties"
+  ];
+}
 async function resolveBounty(arg) {
   let bountyId, title, repoFullName, issueUrl, amountUSD, source, openPRsAtDiscovery, indexNativeId;
   let founderPosting = false;
@@ -35774,10 +35813,7 @@ async function cmdRecord(arg, flags = {}) {
   }
   const b = await resolveBounty(arg);
   if (!b) {
-    console.error(
-      `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`
-    );
-    console.error("  Run `terminalhire bounties` to populate the cache, or pass a full issue URL.");
+    for (const line of await explainUnresolvable(arg)) console.error(line);
     process.exit(1);
   }
   if (b.issueState === "closed") {
@@ -36024,7 +36060,7 @@ terminalhire claim: refusing to record \u2014 read ${b.repoFullName}'s contribut
   );
   console.log("   \u2022 no access to ~/.terminalhire (the executor never needs your profile)");
   console.log(
-    "\n  Next \u2014 start work (forks + clones into an isolated worktree; your terminal stays put):"
+    "\n  Next \u2014 start work (forks + clones into an isolated worktree, then drops you in it):"
   );
   console.log("    terminalhire claim start " + claim.id);
   console.log("  Then publish when it is done (the only step that pushes + opens the PR):");
@@ -36047,10 +36083,7 @@ async function cmdPreview(arg, { json } = {}) {
   }
   const b = await resolveBounty(arg);
   if (!b) {
-    console.error(
-      `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`
-    );
-    console.error("  Run `terminalhire bounties` to populate the cache, or pass a full issue URL.");
+    for (const line of await explainUnresolvable(arg)) console.error(line);
     process.exit(1);
   }
   let policy = null;
@@ -36688,6 +36721,13 @@ async function cmdStart(id, flags = {}) {
     ({ id } = picked);
   }
   let claim = claims.findClaim(id);
+  if (!claim) {
+    const held = heldClaimByShortRef(claims.readClaims(), id);
+    if (held) {
+      claim = held;
+      id = held.id;
+    }
+  }
   let chainedFromRecord = false;
   if (!claim) {
     const b = await resolveBounty(id);
@@ -36727,12 +36767,13 @@ async function cmdStart(id, flags = {}) {
       stillThere = false;
     }
     if (stillThere) {
-      console.log("Already started \u2014 your worktree is ready (your terminal stays put):");
-      console.log(`  cd ${claim.worktreePath}`);
+      console.log("Already started \u2014 your worktree is ready.");
       if (claim.branch) console.log(`  branch: ${claim.branch}`);
       console.log(`
-When it's done:  terminalhire claim submit ${id}`);
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:`);
+      console.log(`    terminalhire claim submit ${id}`);
       await beatFounderPresence(claim);
+      landDeveloperIn(claim.worktreePath, flags);
       return;
     }
   }
@@ -36753,8 +36794,7 @@ ${sanitizeText(claim.title)}`);
       }
     }
     if (outcome.outcome === "delivered") {
-      const workspace = outcome.claim?.worktreePath;
-      if (flags.open && workspace) launchAgentIn(workspace, flags.open);
+      landDeveloperIn(outcome.claim?.worktreePath, flags);
       return;
     }
     if (outcome.outcome === "pending") {
@@ -36874,10 +36914,9 @@ terminalhire claim: not started \u2014 starting forks ${claim.repoFullName} to y
 \u2713 Started: ${claim.title}`);
   console.log(`  fork:   ${forkFullName}`);
   console.log(`  branch: ${branch}`);
-  console.log("\n  Your isolated worktree is ready \u2014 your current terminal is untouched:");
-  console.log(`    cd ${toplevel}`);
-  console.log("\n  When the work is done (the only step that pushes + opens the PR):");
+  console.log("\n  Commit as you go. When it is done (the only step that pushes + opens the PR):");
   console.log(`    terminalhire claim submit ${id}`);
+  landDeveloperIn(toplevel, flags);
 }
 async function cmdStartHere(claims, claim, flags = {}) {
   let toplevel;
@@ -36998,6 +37037,45 @@ function launchAgentIn(dest, agentName, { spawnFn, log = console.log } = {}) {
   }
   return { launched: true, reason: null };
 }
+function heldClaimByShortRef(allClaims, arg) {
+  if (!looksLikeShortRef(arg)) return null;
+  if (!Array.isArray(allClaims)) return null;
+  return allClaims.find((c) => c?.id && opportunityShortToken(c.id) === arg) ?? null;
+}
+function landDeveloperIn(dest, flags = {}, deps = {}) {
+  const { spawnFn, log = console.log, isTTY, shellPath } = deps;
+  if (!dest) return { landed: false, reason: "no-workspace" };
+  const cdLine = () => log(`
+  cd ${dest}`);
+  if (flags.open) {
+    const result2 = launchAgentIn(dest, flags.open, { spawnFn, log });
+    return { landed: result2.launched, reason: result2.reason };
+  }
+  if (flags.stay) {
+    cdLine();
+    return { landed: false, reason: "declined" };
+  }
+  const tty = isTTY ?? Boolean(process.stdout?.isTTY);
+  if (!tty) {
+    cdLine();
+    return { landed: false, reason: "not-a-tty" };
+  }
+  const shell = Object.hasOwn(deps, "shellPath") ? shellPath : process.env.SHELL;
+  if (typeof shell !== "string" || !shell.startsWith("/")) {
+    cdLine();
+    return { landed: false, reason: "no-shell" };
+  }
+  log(`
+  You're in the workspace now \u2014 \`exit\` brings you back here.`);
+  const spawn6 = spawnFn ?? spawnSync8;
+  const result = spawn6(shell, [], { cwd: dest, stdio: "inherit", shell: false });
+  if (result?.error) {
+    log(`  ${shell} would not start \u2014 the workspace is ready anyway.`);
+    cdLine();
+    return { landed: false, reason: "shell-failed" };
+  }
+  return { landed: true, reason: null };
+}
 function renderServerRefusal(status, body) {
   const code = body && typeof body.error === "string" ? body.error : null;
   const prose = body && typeof body.message === "string" ? body.message : null;
@@ -37545,11 +37623,9 @@ async function cmdSliceFullTier(claims, id, local, fullTierBody, flags, cloneRep
   printWorkspacePack(pack);
   console.log(
     `
-  Author your change there (commit as you go), then:  terminalhire claim submit ${claim.id}`
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:
+    terminalhire claim submit ${claim.id}`
   );
-  if (pack.agents.written === true) {
-    console.log(`  Working with an agent? Point it at ${AGENTS_REL_PATH} first.`);
-  }
   await beatFounderPresence(working ?? claim);
 }
 async function cmdSlice(id, flags = {}) {
@@ -37559,8 +37635,7 @@ async function cmdSlice(id, flags = {}) {
   }
   const outcome = await attemptSliceDelivery(id, flags);
   exitOnSliceOutcome(outcome);
-  const workspace = outcome.claim?.worktreePath;
-  if (flags.open && workspace) launchAgentIn(workspace, flags.open);
+  landDeveloperIn(outcome.claim?.worktreePath, flags);
 }
 function exitOnSliceOutcome(outcome) {
   if (outcome.outcome === "delivered") return;
@@ -37754,11 +37829,9 @@ async function attemptSliceDelivery(id, flags = {}) {
   printWorkspacePack(pack);
   console.log(
     `
-  Author your change there (commit as you go), then:  terminalhire claim submit ${claim.id}`
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:
+    terminalhire claim submit ${claim.id}`
   );
-  if (pack.agents.written === true) {
-    console.log(`  Working with an agent? Point it at ${AGENTS_REL_PATH} first.`);
-  }
   await beatFounderPresence(working ?? claim);
   return { outcome: "delivered", claim: working ?? claim };
 }
@@ -39094,6 +39167,7 @@ export {
   cmdSubmit,
   countOpenPRsReferencingIssue,
   diffContention,
+  explainUnresolvable,
   explicitForkConsent,
   fetchFounderApprovals,
   findClaimableByShortRef,
@@ -39102,11 +39176,13 @@ export {
   fmtContestedWarning,
   founderClaimStanding,
   founderPostingIdOf,
+  heldClaimByShortRef,
   inferSubmitClaim,
   isContested,
   isStrayArgShortRefClaim,
   isTerminalRunStatus,
   isVerblessShortRefClaim,
+  landDeveloperIn,
   launchAgentIn,
   listMergedPRsReferencingIssue,
   listOpenPRsReferencingIssue,

package/dist/bin/jpi-dispatch.js

@@ -33631,6 +33631,9 @@ function labelSelector(labels) {
     throw new EnvRunError("labels object is empty; pass at least one label or omit it");
   return `${first[0]}=${first[1]}`;
 }
+function withUserScriptPath(command) {
+  return `PATH="$PATH:$HOME/.local/bin"; export PATH; ${command}`;
+}
 async function runStep(containment, r) {
   const spec = {
     profile: r.profile,
@@ -33645,7 +33648,7 @@ async function runStep(containment, r) {
     pathDomain: r.pathDomain,
     guestUser: r.guestUser,
     program: "/bin/sh",
-    args: ["-c", r.command]
+    args: ["-c", withUserScriptPath(r.command)]
   };
   const startedAt = Date.now();
   const res = await containment.run(spec, r.env, {
@@ -39678,6 +39681,7 @@ __export(jpi_claim_exports, {
   cmdSubmit: () => cmdSubmit,
   countOpenPRsReferencingIssue: () => countOpenPRsReferencingIssue,
   diffContention: () => diffContention,
+  explainUnresolvable: () => explainUnresolvable,
   explicitForkConsent: () => explicitForkConsent,
   fetchFounderApprovals: () => fetchFounderApprovals,
   findClaimableByShortRef: () => findClaimableByShortRef,
@@ -39686,11 +39690,13 @@ __export(jpi_claim_exports, {
   fmtContestedWarning: () => fmtContestedWarning,
   founderClaimStanding: () => founderClaimStanding,
   founderPostingIdOf: () => founderPostingIdOf,
+  heldClaimByShortRef: () => heldClaimByShortRef,
   inferSubmitClaim: () => inferSubmitClaim,
   isContested: () => isContested,
   isStrayArgShortRefClaim: () => isStrayArgShortRefClaim,
   isTerminalRunStatus: () => isTerminalRunStatus,
   isVerblessShortRefClaim: () => isVerblessShortRefClaim,
+  landDeveloperIn: () => landDeveloperIn,
   launchAgentIn: () => launchAgentIn,
   listMergedPRsReferencingIssue: () => listMergedPRsReferencingIssue,
   listOpenPRsReferencingIssue: () => listOpenPRsReferencingIssue,
@@ -40502,6 +40508,42 @@ function printNextSteps(list) {
     console.log(`    ${s.cmd.padEnd(width)}   \u2014 ${s.why}`);
   }
 }
+async function explainUnresolvable(arg) {
+  const generic = [
+    `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`,
+    "  Run `terminalhire bounties` to populate the cache, or pass a full issue URL."
+  ];
+  if (!looksLikeShortRef(arg)) return generic;
+  try {
+    const { readClaims: readClaims2 } = await Promise.resolve().then(() => (init_claims(), claims_exports));
+    const mine = readClaims2().find((c) => c?.id && opportunityShortToken(c.id) === arg);
+    if (mine) {
+      return [
+        `terminalhire claim: you have already claimed '${arg}'.`,
+        `  ${mine.title ?? mine.id}`,
+        "  A claimed posting leaves the public index, so it cannot be claimed again.",
+        "",
+        `  Get your workspace:   terminalhire claim start ${mine.id}`,
+        `  See where it stands:  terminalhire claim status ${mine.id}`
+      ];
+    }
+  } catch {
+  }
+  return [
+    `terminalhire claim: '${arg}' did not resolve to anything you can claim.`,
+    "  It has the shape of a claim token, so one of two things is true, and this",
+    "  command cannot tell them apart:",
+    "",
+    "    \u2022 the posting was claimed or withdrawn. A claimed posting leaves the",
+    "      public index, and `terminalhire bounties` will never bring it back.",
+    "    \u2022 the token is unknown here \u2014 mistyped, or minted against a different",
+    "      environment than the one this command is pointed at.",
+    "",
+    `  Open it:            ${API_URL7}/c/${arg}`,
+    "  Already yours?      terminalhire claim list",
+    "  Refresh the index:  terminalhire bounties"
+  ];
+}
 async function resolveBounty(arg) {
   let bountyId, title, repoFullName, issueUrl, amountUSD, source, openPRsAtDiscovery, indexNativeId;
   let founderPosting = false;
@@ -40956,10 +40998,7 @@ async function cmdRecord(arg, flags = {}) {
   }
   const b = await resolveBounty(arg);
   if (!b) {
-    console.error(
-      `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`
-    );
-    console.error("  Run `terminalhire bounties` to populate the cache, or pass a full issue URL.");
+    for (const line of await explainUnresolvable(arg)) console.error(line);
     process.exit(1);
   }
   if (b.issueState === "closed") {
@@ -41206,7 +41245,7 @@ terminalhire claim: refusing to record \u2014 read ${b.repoFullName}'s contribut
   );
   console.log("   \u2022 no access to ~/.terminalhire (the executor never needs your profile)");
   console.log(
-    "\n  Next \u2014 start work (forks + clones into an isolated worktree; your terminal stays put):"
+    "\n  Next \u2014 start work (forks + clones into an isolated worktree, then drops you in it):"
   );
   console.log("    terminalhire claim start " + claim.id);
   console.log("  Then publish when it is done (the only step that pushes + opens the PR):");
@@ -41229,10 +41268,7 @@ async function cmdPreview(arg, { json } = {}) {
   }
   const b = await resolveBounty(arg);
   if (!b) {
-    console.error(
-      `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`
-    );
-    console.error("  Run `terminalhire bounties` to populate the cache, or pass a full issue URL.");
+    for (const line of await explainUnresolvable(arg)) console.error(line);
     process.exit(1);
   }
   let policy = null;
@@ -41869,6 +41905,13 @@ async function cmdStart(id, flags = {}) {
     ({ id } = picked);
   }
   let claim = claims.findClaim(id);
+  if (!claim) {
+    const held = heldClaimByShortRef(claims.readClaims(), id);
+    if (held) {
+      claim = held;
+      id = held.id;
+    }
+  }
   let chainedFromRecord = false;
   if (!claim) {
     const b = await resolveBounty(id);
@@ -41908,12 +41951,13 @@ async function cmdStart(id, flags = {}) {
       stillThere = false;
     }
     if (stillThere) {
-      console.log("Already started \u2014 your worktree is ready (your terminal stays put):");
-      console.log(`  cd ${claim.worktreePath}`);
+      console.log("Already started \u2014 your worktree is ready.");
       if (claim.branch) console.log(`  branch: ${claim.branch}`);
       console.log(`
-When it's done:  terminalhire claim submit ${id}`);
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:`);
+      console.log(`    terminalhire claim submit ${id}`);
       await beatFounderPresence(claim);
+      landDeveloperIn(claim.worktreePath, flags);
       return;
     }
   }
@@ -41934,8 +41978,7 @@ ${sanitizeText(claim.title)}`);
       }
     }
     if (outcome.outcome === "delivered") {
-      const workspace = outcome.claim?.worktreePath;
-      if (flags.open && workspace) launchAgentIn(workspace, flags.open);
+      landDeveloperIn(outcome.claim?.worktreePath, flags);
       return;
     }
     if (outcome.outcome === "pending") {
@@ -42055,10 +42098,9 @@ terminalhire claim: not started \u2014 starting forks ${claim.repoFullName} to y
 \u2713 Started: ${claim.title}`);
   console.log(`  fork:   ${forkFullName}`);
   console.log(`  branch: ${branch}`);
-  console.log("\n  Your isolated worktree is ready \u2014 your current terminal is untouched:");
-  console.log(`    cd ${toplevel}`);
-  console.log("\n  When the work is done (the only step that pushes + opens the PR):");
+  console.log("\n  Commit as you go. When it is done (the only step that pushes + opens the PR):");
   console.log(`    terminalhire claim submit ${id}`);
+  landDeveloperIn(toplevel, flags);
 }
 async function cmdStartHere(claims, claim, flags = {}) {
   let toplevel;
@@ -42169,6 +42211,45 @@ function launchAgentIn(dest, agentName, { spawnFn, log = console.log } = {}) {
   }
   return { launched: true, reason: null };
 }
+function heldClaimByShortRef(allClaims, arg) {
+  if (!looksLikeShortRef(arg)) return null;
+  if (!Array.isArray(allClaims)) return null;
+  return allClaims.find((c) => c?.id && opportunityShortToken(c.id) === arg) ?? null;
+}
+function landDeveloperIn(dest, flags = {}, deps = {}) {
+  const { spawnFn, log = console.log, isTTY, shellPath } = deps;
+  if (!dest) return { landed: false, reason: "no-workspace" };
+  const cdLine = () => log(`
+  cd ${dest}`);
+  if (flags.open) {
+    const result2 = launchAgentIn(dest, flags.open, { spawnFn, log });
+    return { landed: result2.launched, reason: result2.reason };
+  }
+  if (flags.stay) {
+    cdLine();
+    return { landed: false, reason: "declined" };
+  }
+  const tty = isTTY ?? Boolean(process.stdout?.isTTY);
+  if (!tty) {
+    cdLine();
+    return { landed: false, reason: "not-a-tty" };
+  }
+  const shell = Object.hasOwn(deps, "shellPath") ? shellPath : process.env.SHELL;
+  if (typeof shell !== "string" || !shell.startsWith("/")) {
+    cdLine();
+    return { landed: false, reason: "no-shell" };
+  }
+  log(`
+  You're in the workspace now \u2014 \`exit\` brings you back here.`);
+  const spawn8 = spawnFn ?? spawnSync9;
+  const result = spawn8(shell, [], { cwd: dest, stdio: "inherit", shell: false });
+  if (result?.error) {
+    log(`  ${shell} would not start \u2014 the workspace is ready anyway.`);
+    cdLine();
+    return { landed: false, reason: "shell-failed" };
+  }
+  return { landed: true, reason: null };
+}
 function renderServerRefusal(status, body) {
   const code = body && typeof body.error === "string" ? body.error : null;
   const prose = body && typeof body.message === "string" ? body.message : null;
@@ -42697,11 +42778,9 @@ async function cmdSliceFullTier(claims, id, local, fullTierBody, flags, cloneRep
   printWorkspacePack(pack);
   console.log(
     `
-  Author your change there (commit as you go), then:  terminalhire claim submit ${claim.id}`
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:
+    terminalhire claim submit ${claim.id}`
   );
-  if (pack.agents.written === true) {
-    console.log(`  Working with an agent? Point it at ${AGENTS_REL_PATH} first.`);
-  }
   await beatFounderPresence(working ?? claim);
 }
 async function cmdSlice(id, flags = {}) {
@@ -42711,8 +42790,7 @@ async function cmdSlice(id, flags = {}) {
   }
   const outcome = await attemptSliceDelivery(id, flags);
   exitOnSliceOutcome(outcome);
-  const workspace = outcome.claim?.worktreePath;
-  if (flags.open && workspace) launchAgentIn(workspace, flags.open);
+  landDeveloperIn(outcome.claim?.worktreePath, flags);
 }
 function exitOnSliceOutcome(outcome) {
   if (outcome.outcome === "delivered") return;
@@ -42906,11 +42984,9 @@ async function attemptSliceDelivery(id, flags = {}) {
   printWorkspacePack(pack);
   console.log(
     `
-  Author your change there (commit as you go), then:  terminalhire claim submit ${claim.id}`
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:
+    terminalhire claim submit ${claim.id}`
   );
-  if (pack.agents.written === true) {
-    console.log(`  Working with an agent? Point it at ${AGENTS_REL_PATH} first.`);
-  }
   await beatFounderPresence(working ?? claim);
   return { outcome: "delivered", claim: working ?? claim };
 }

package/dist/bin/jpi-mcp.js

@@ -28508,6 +28508,9 @@ function labelSelector(labels) {
     throw new EnvRunError("labels object is empty; pass at least one label or omit it");
   return `${first[0]}=${first[1]}`;
 }
+function withUserScriptPath(command) {
+  return `PATH="$PATH:$HOME/.local/bin"; export PATH; ${command}`;
+}
 async function runStep(containment, r) {
   const spec = {
     profile: r.profile,
@@ -28522,7 +28525,7 @@ async function runStep(containment, r) {
     pathDomain: r.pathDomain,
     guestUser: r.guestUser,
     program: "/bin/sh",
-    args: ["-c", r.command]
+    args: ["-c", withUserScriptPath(r.command)]
   };
   const startedAt = Date.now();
   const res = await containment.run(spec, r.env, {
@@ -34555,6 +34558,7 @@ __export(jpi_claim_exports, {
   cmdSubmit: () => cmdSubmit,
   countOpenPRsReferencingIssue: () => countOpenPRsReferencingIssue,
   diffContention: () => diffContention,
+  explainUnresolvable: () => explainUnresolvable,
   explicitForkConsent: () => explicitForkConsent,
   fetchFounderApprovals: () => fetchFounderApprovals,
   findClaimableByShortRef: () => findClaimableByShortRef,
@@ -34563,11 +34567,13 @@ __export(jpi_claim_exports, {
   fmtContestedWarning: () => fmtContestedWarning,
   founderClaimStanding: () => founderClaimStanding,
   founderPostingIdOf: () => founderPostingIdOf,
+  heldClaimByShortRef: () => heldClaimByShortRef,
   inferSubmitClaim: () => inferSubmitClaim,
   isContested: () => isContested,
   isStrayArgShortRefClaim: () => isStrayArgShortRefClaim,
   isTerminalRunStatus: () => isTerminalRunStatus,
   isVerblessShortRefClaim: () => isVerblessShortRefClaim,
+  landDeveloperIn: () => landDeveloperIn,
   launchAgentIn: () => launchAgentIn,
   listMergedPRsReferencingIssue: () => listMergedPRsReferencingIssue,
   listOpenPRsReferencingIssue: () => listOpenPRsReferencingIssue,
@@ -35379,6 +35385,42 @@ function printNextSteps(list) {
     console.log(`    ${s.cmd.padEnd(width)}   \u2014 ${s.why}`);
   }
 }
+async function explainUnresolvable(arg) {
+  const generic = [
+    `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`,
+    "  Run `terminalhire bounties` to populate the cache, or pass a full issue URL."
+  ];
+  if (!looksLikeShortRef(arg)) return generic;
+  try {
+    const { readClaims: readClaims2 } = await Promise.resolve().then(() => (init_claims(), claims_exports));
+    const mine = readClaims2().find((c) => c?.id && opportunityShortToken(c.id) === arg);
+    if (mine) {
+      return [
+        `terminalhire claim: you have already claimed '${arg}'.`,
+        `  ${mine.title ?? mine.id}`,
+        "  A claimed posting leaves the public index, so it cannot be claimed again.",
+        "",
+        `  Get your workspace:   terminalhire claim start ${mine.id}`,
+        `  See where it stands:  terminalhire claim status ${mine.id}`
+      ];
+    }
+  } catch {
+  }
+  return [
+    `terminalhire claim: '${arg}' did not resolve to anything you can claim.`,
+    "  It has the shape of a claim token, so one of two things is true, and this",
+    "  command cannot tell them apart:",
+    "",
+    "    \u2022 the posting was claimed or withdrawn. A claimed posting leaves the",
+    "      public index, and `terminalhire bounties` will never bring it back.",
+    "    \u2022 the token is unknown here \u2014 mistyped, or minted against a different",
+    "      environment than the one this command is pointed at.",
+    "",
+    `  Open it:            ${API_URL}/c/${arg}`,
+    "  Already yours?      terminalhire claim list",
+    "  Refresh the index:  terminalhire bounties"
+  ];
+}
 async function resolveBounty(arg) {
   let bountyId, title, repoFullName, issueUrl, amountUSD, source, openPRsAtDiscovery, indexNativeId;
   let founderPosting = false;
@@ -35833,10 +35875,7 @@ async function cmdRecord(arg, flags = {}) {
   }
   const b = await resolveBounty(arg);
   if (!b) {
-    console.error(
-      `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`
-    );
-    console.error("  Run `terminalhire bounties` to populate the cache, or pass a full issue URL.");
+    for (const line of await explainUnresolvable(arg)) console.error(line);
     process.exit(1);
   }
   if (b.issueState === "closed") {
@@ -36083,7 +36122,7 @@ terminalhire claim: refusing to record \u2014 read ${b.repoFullName}'s contribut
   );
   console.log("   \u2022 no access to ~/.terminalhire (the executor never needs your profile)");
   console.log(
-    "\n  Next \u2014 start work (forks + clones into an isolated worktree; your terminal stays put):"
+    "\n  Next \u2014 start work (forks + clones into an isolated worktree, then drops you in it):"
   );
   console.log("    terminalhire claim start " + claim.id);
   console.log("  Then publish when it is done (the only step that pushes + opens the PR):");
@@ -36106,10 +36145,7 @@ async function cmdPreview(arg, { json } = {}) {
   }
   const b = await resolveBounty(arg);
   if (!b) {
-    console.error(
-      `terminalhire claim: '${arg}' is not in the index cache and is not a GitHub issue URL.`
-    );
-    console.error("  Run `terminalhire bounties` to populate the cache, or pass a full issue URL.");
+    for (const line of await explainUnresolvable(arg)) console.error(line);
     process.exit(1);
   }
   let policy = null;
@@ -36746,6 +36782,13 @@ async function cmdStart(id, flags = {}) {
     ({ id } = picked);
   }
   let claim = claims.findClaim(id);
+  if (!claim) {
+    const held = heldClaimByShortRef(claims.readClaims(), id);
+    if (held) {
+      claim = held;
+      id = held.id;
+    }
+  }
   let chainedFromRecord = false;
   if (!claim) {
     const b = await resolveBounty(id);
@@ -36785,12 +36828,13 @@ async function cmdStart(id, flags = {}) {
       stillThere = false;
     }
     if (stillThere) {
-      console.log("Already started \u2014 your worktree is ready (your terminal stays put):");
-      console.log(`  cd ${claim.worktreePath}`);
+      console.log("Already started \u2014 your worktree is ready.");
       if (claim.branch) console.log(`  branch: ${claim.branch}`);
       console.log(`
-When it's done:  terminalhire claim submit ${id}`);
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:`);
+      console.log(`    terminalhire claim submit ${id}`);
       await beatFounderPresence(claim);
+      landDeveloperIn(claim.worktreePath, flags);
       return;
     }
   }
@@ -36811,8 +36855,7 @@ ${sanitizeText(claim.title)}`);
       }
     }
     if (outcome.outcome === "delivered") {
-      const workspace = outcome.claim?.worktreePath;
-      if (flags.open && workspace) launchAgentIn(workspace, flags.open);
+      landDeveloperIn(outcome.claim?.worktreePath, flags);
       return;
     }
     if (outcome.outcome === "pending") {
@@ -36932,10 +36975,9 @@ terminalhire claim: not started \u2014 starting forks ${claim.repoFullName} to y
 \u2713 Started: ${claim.title}`);
   console.log(`  fork:   ${forkFullName}`);
   console.log(`  branch: ${branch}`);
-  console.log("\n  Your isolated worktree is ready \u2014 your current terminal is untouched:");
-  console.log(`    cd ${toplevel}`);
-  console.log("\n  When the work is done (the only step that pushes + opens the PR):");
+  console.log("\n  Commit as you go. When it is done (the only step that pushes + opens the PR):");
   console.log(`    terminalhire claim submit ${id}`);
+  landDeveloperIn(toplevel, flags);
 }
 async function cmdStartHere(claims, claim, flags = {}) {
   let toplevel;
@@ -37046,6 +37088,45 @@ function launchAgentIn(dest, agentName, { spawnFn, log = console.log } = {}) {
   }
   return { launched: true, reason: null };
 }
+function heldClaimByShortRef(allClaims, arg) {
+  if (!looksLikeShortRef(arg)) return null;
+  if (!Array.isArray(allClaims)) return null;
+  return allClaims.find((c) => c?.id && opportunityShortToken(c.id) === arg) ?? null;
+}
+function landDeveloperIn(dest, flags = {}, deps = {}) {
+  const { spawnFn, log = console.log, isTTY, shellPath } = deps;
+  if (!dest) return { landed: false, reason: "no-workspace" };
+  const cdLine = () => log(`
+  cd ${dest}`);
+  if (flags.open) {
+    const result2 = launchAgentIn(dest, flags.open, { spawnFn, log });
+    return { landed: result2.launched, reason: result2.reason };
+  }
+  if (flags.stay) {
+    cdLine();
+    return { landed: false, reason: "declined" };
+  }
+  const tty = isTTY ?? Boolean(process.stdout?.isTTY);
+  if (!tty) {
+    cdLine();
+    return { landed: false, reason: "not-a-tty" };
+  }
+  const shell = Object.hasOwn(deps, "shellPath") ? shellPath : process.env.SHELL;
+  if (typeof shell !== "string" || !shell.startsWith("/")) {
+    cdLine();
+    return { landed: false, reason: "no-shell" };
+  }
+  log(`
+  You're in the workspace now \u2014 \`exit\` brings you back here.`);
+  const spawn6 = spawnFn ?? spawnSync8;
+  const result = spawn6(shell, [], { cwd: dest, stdio: "inherit", shell: false });
+  if (result?.error) {
+    log(`  ${shell} would not start \u2014 the workspace is ready anyway.`);
+    cdLine();
+    return { landed: false, reason: "shell-failed" };
+  }
+  return { landed: true, reason: null };
+}
 function renderServerRefusal(status, body) {
   const code = body && typeof body.error === "string" ? body.error : null;
   const prose = body && typeof body.message === "string" ? body.message : null;
@@ -37574,11 +37655,9 @@ async function cmdSliceFullTier(claims, id, local, fullTierBody, flags, cloneRep
   printWorkspacePack(pack);
   console.log(
     `
-  Author your change there (commit as you go), then:  terminalhire claim submit ${claim.id}`
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:
+    terminalhire claim submit ${claim.id}`
   );
-  if (pack.agents.written === true) {
-    console.log(`  Working with an agent? Point it at ${AGENTS_REL_PATH} first.`);
-  }
   await beatFounderPresence(working ?? claim);
 }
 async function cmdSlice(id, flags = {}) {
@@ -37588,8 +37667,7 @@ async function cmdSlice(id, flags = {}) {
   }
   const outcome = await attemptSliceDelivery(id, flags);
   exitOnSliceOutcome(outcome);
-  const workspace = outcome.claim?.worktreePath;
-  if (flags.open && workspace) launchAgentIn(workspace, flags.open);
+  landDeveloperIn(outcome.claim?.worktreePath, flags);
 }
 function exitOnSliceOutcome(outcome) {
   if (outcome.outcome === "delivered") return;
@@ -37783,11 +37861,9 @@ async function attemptSliceDelivery(id, flags = {}) {
   printWorkspacePack(pack);
   console.log(
     `
-  Author your change there (commit as you go), then:  terminalhire claim submit ${claim.id}`
+  Commit as you go \u2014 your commits ARE the patch. Hand it back with:
+    terminalhire claim submit ${claim.id}`
   );
-  if (pack.agents.written === true) {
-    console.log(`  Working with an agent? Point it at ${AGENTS_REL_PATH} first.`);
-  }
   await beatFounderPresence(working ?? claim);
   return { outcome: "delivered", claim: working ?? claim };
 }

package/dist/bin/jpi-run.js

@@ -2101,6 +2101,9 @@ function labelSelector(labels) {
     throw new EnvRunError("labels object is empty; pass at least one label or omit it");
   return `${first[0]}=${first[1]}`;
 }
+function withUserScriptPath(command) {
+  return `PATH="$PATH:$HOME/.local/bin"; export PATH; ${command}`;
+}
 async function runStep(containment, r) {
   const spec = {
     profile: r.profile,
@@ -2115,7 +2118,7 @@ async function runStep(containment, r) {
     pathDomain: r.pathDomain,
     guestUser: r.guestUser,
     program: "/bin/sh",
-    args: ["-c", r.command]
+    args: ["-c", withUserScriptPath(r.command)]
   };
   const startedAt = Date.now();
   const res = await containment.run(spec, r.env, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminalhire",
-  "version": "0.42.14",
+  "version": "0.42.15",
   "description": "Developer jobs and paid bounties, matched in the terminal — ambient matches in the Claude Code spinner. Claim a scoped bounty and get paid when the poster accepts it.",
   "repository": {
     "type": "git",