terminalhire 0.26.2 → 0.28.0

package/dist/bin/jpi-claim.js

@@ -8882,6 +8882,10 @@ ${p.body ?? ""}`)) {
   }
   return matched;
 }
+function selectCompetingPrs(prs, selfLogin) {
+  if (!Array.isArray(prs)) return [];
+  return prs.filter((pr) => pr && pr.author !== selfLogin);
+}
 async function listOpenPRsReferencingIssue(repoFullName, issueNumber) {
   try {
     const res = await fetch(`${GH_API2}/repos/${repoFullName}/pulls?state=open&per_page=100`, {
@@ -8947,6 +8951,67 @@ async function fetchIssue(repoFullName, issueNumber) {
     return null;
   }
 }
+var ASSIGNMENT_MARKER = "<!-- terminalhire:assignment-request -->";
+var TAKE_BOT_REPOS = /* @__PURE__ */ new Set(["paradedb/paradedb"]);
+function buildAssignmentComment(repoFullName) {
+  const usesTakeBot = TAKE_BOT_REPOS.has(repoFullName.toLowerCase());
+  const body = usesTakeBot ? "/take" : `I'd like to work on this \u2014 could I be assigned? Thanks!
+
+${ASSIGNMENT_MARKER}`;
+  return { usesTakeBot, body };
+}
+async function hasPriorAssignmentRequest(repoFullName, issueNumber, login) {
+  try {
+    const res = await fetch(
+      `${GH_API2}/repos/${repoFullName}/issues/${issueNumber}/comments?per_page=100&sort=created&direction=desc`,
+      { headers: GH_HEADERS2, signal: AbortSignal.timeout(1e4) }
+    );
+    if (!res.ok) return false;
+    const comments = await res.json();
+    if (!Array.isArray(comments)) return false;
+    return comments.some(
+      (c) => c && c.user && c.user.login === login && typeof c.body === "string" && c.body.includes(ASSIGNMENT_MARKER)
+    );
+  } catch {
+    return false;
+  }
+}
+async function requestIssueAssignment(claim, flags = {}, ghUser) {
+  if (flags["no-assign"]) {
+    console.log("  (--no-assign \u2014 skipping the assignment request; request it manually before working)");
+    return;
+  }
+  const parsed = parseGitHubUrl(claim.issueUrl);
+  if (!parsed) return;
+  const { repoFullName, number } = parsed;
+  let login = ghUser;
+  if (!login) {
+    try {
+      login = await sh("gh", ["api", "user", "-q", ".login"]);
+    } catch {
+      console.log("  (assignment not requested: 'gh' not authenticated \u2014 comment on the issue manually before working)");
+      return;
+    }
+  }
+  const issue = await fetchIssue(repoFullName, number);
+  if (issue && issue.assignees.includes(login)) {
+    console.log(`  \u2713 Already assigned to @${login} on ${repoFullName}#${number}.`);
+    return;
+  }
+  const { usesTakeBot, body } = buildAssignmentComment(repoFullName);
+  if (!usesTakeBot && await hasPriorAssignmentRequest(repoFullName, number, login)) {
+    console.log(`  \u2713 Assignment already requested on ${repoFullName}#${number}.`);
+    return;
+  }
+  try {
+    await sh("gh", ["issue", "comment", String(number), "--repo", repoFullName, "--body", body]);
+    console.log(
+      usesTakeBot ? `  \u2713 Requested assignment via /take on ${repoFullName}#${number}.` : `  \u2713 Requested assignment on ${repoFullName}#${number}.`
+    );
+  } catch (err) {
+    console.log(`  (could not post the assignment request: ${err.stderr || err.message || err} \u2014 do it manually before working)`);
+  }
+}
 async function pollPR(prUrl) {
   const p = parseGitHubUrl(prUrl);
   if (!p) return null;
@@ -9162,10 +9227,19 @@ terminalhire claim: refusing to record \u2014 read ${b.repoFullName}'s contribut
   console.log("   \u2022 MUST NOT `git push` or `gh pr` \u2014 pushing happens only via `terminalhire submit`");
   console.log("   \u2022 clone + static analysis + patch only; NO test/build execution without explicit approval");
   console.log("   \u2022 no access to ~/.terminalhire (the executor never needs your profile)");
-  console.log("\n  Next:");
-  console.log("   1. record the worktree:  terminalhire claim attach " + claim.id + " --worktree <path> --branch <branch>");
-  console.log("   2. do the work + review, then mark it cleared:  terminalhire claim update " + claim.id + " ready");
-  console.log("   3. publish (pushes to your fork + opens the PR):  terminalhire claim submit " + claim.id);
+  console.log("\n  Next \u2014 start work (forks + clones into an isolated worktree; your terminal stays put):");
+  console.log("    terminalhire claim start " + claim.id);
+  console.log("  Then publish when it is done (the only step that pushes + opens the PR):");
+  console.log("    terminalhire claim submit " + claim.id);
+  if (flags.start) {
+    await cmdStart(claim.id, { start: true });
+  } else if (process.stdin.isTTY && !flags["no-start"]) {
+    const go = await confirm(`
+  Fork ${claim.repoFullName} and start now? (y/N) `);
+    if (go) await cmdStart(claim.id, { start: true });
+    else console.log(`
+  Saved. Start anytime:  terminalhire claim start ${claim.id}`);
+  }
 }
 async function cmdPreview(arg, { json } = {}) {
   if (!arg) {
@@ -9362,6 +9436,181 @@ async function cmdAttach(id, worktree, branch) {
   claims.updateClaim(id, { worktreePath: toplevel, branch });
   console.log(`Attached ${id}: worktree=${toplevel} branch=${branch}`);
 }
+function workDirFor(repoFullName, issueNumber) {
+  const [owner, repo] = String(repoFullName).split("/");
+  const suffix = issueNumber ? `-${issueNumber}` : "";
+  return join7(homedir6(), "terminalhire", "work", `${owner}-${repo}${suffix}`);
+}
+function startBranchFor(repoFullName, issueNumber) {
+  const repo = String(repoFullName).split("/")[1] || "claim";
+  return `th/${repo}-${issueNumber || "work"}`;
+}
+function explicitForkConsent(flags = {}) {
+  return Boolean(flags.start) || Boolean(flags.fork);
+}
+async function ensureForkExists(repoFullName, ghUser) {
+  const repoShort = repoFullName.split("/")[1];
+  const forkFullName = `${ghUser}/${repoShort}`;
+  await sh("gh", ["repo", "fork", repoFullName, "--clone=false"]);
+  let isFork = false;
+  try {
+    isFork = await sh("gh", ["api", `repos/${forkFullName}`, "--jq", ".fork"]) === "true";
+  } catch {
+    isFork = false;
+  }
+  if (!isFork) throw new Error(`fork ${forkFullName} created but could not be verified as a fork`);
+  return forkFullName;
+}
+async function cmdStart(id, flags = {}) {
+  const claims = await Promise.resolve().then(() => (init_claims(), claims_exports));
+  if (!id) {
+    const startable = claims.listClaims({ active: true }).filter((c) => c.state === "claimed");
+    if (startable.length === 0) {
+      console.log("No claims ready to start. Claim one first:  terminalhire claim <ref>");
+      return;
+    }
+    console.log(`
+${startable.length} claim${startable.length === 1 ? "" : "s"} ready to start:
+`);
+    for (const c of startable) {
+      console.log(`  ${c.title}`);
+      console.log(`    terminalhire claim start ${c.id}`);
+    }
+    console.log("\nRun the command under the one you want to start.");
+    return;
+  }
+  const claim = claims.findClaim(id);
+  if (!claim) {
+    console.error(`terminalhire claim: no claim with id '${id}'.`);
+    process.exit(1);
+  }
+  if (claim.worktreePath) {
+    let stillThere = false;
+    try {
+      stillThere = await sh("git", ["-C", claim.worktreePath, "rev-parse", "--show-toplevel"]) === claim.worktreePath;
+    } catch {
+      stillThere = false;
+    }
+    if (stillThere) {
+      console.log("Already started \u2014 your worktree is ready (your terminal stays put):");
+      console.log(`  cd ${claim.worktreePath}`);
+      if (claim.branch) console.log(`  branch: ${claim.branch}`);
+      console.log(`
+When it's done:  terminalhire claim submit ${id}`);
+      return;
+    }
+  }
+  if (flags.here) {
+    await cmdStartHere(claims, claim, flags);
+    return;
+  }
+  let ghUser;
+  try {
+    ghUser = await sh("gh", ["api", "user", "-q", ".login"]);
+  } catch {
+    console.error("terminalhire claim: 'gh' CLI not available or not authenticated. Run 'gh auth login'.");
+    process.exit(1);
+  }
+  let consented = explicitForkConsent(flags);
+  if (!consented && process.stdin.isTTY) {
+    consented = await confirm(`
+  Fork ${claim.repoFullName} to @${ghUser} and clone it to start? (y/N) `);
+  }
+  if (!consented) {
+    console.error(
+      `
+terminalhire claim: not started \u2014 starting forks ${claim.repoFullName} to your GitHub account (a network write).
+  Re-run in a terminal to confirm interactively, or pass --fork to consent non-interactively.`
+    );
+    process.exit(1);
+  }
+  const issueNumber = (parseGitHubUrl(claim.issueUrl) || {}).number;
+  const destDir = workDirFor(claim.repoFullName, issueNumber);
+  if (existsSync6(destDir)) {
+    console.error(
+      `terminalhire claim: ${destDir} already exists \u2014 refusing to clobber it.
+  Remove it and retry, or attach it: terminalhire claim attach ${id} --worktree ${destDir} --branch <branch>`
+    );
+    process.exit(1);
+  }
+  mkdirSync6(join7(homedir6(), "terminalhire", "work"), { recursive: true });
+  let forkFullName;
+  try {
+    forkFullName = await ensureForkExists(claim.repoFullName, ghUser);
+  } catch (err) {
+    console.error(`terminalhire claim: could not create your fork of ${claim.repoFullName}. ${err.message ?? err}`);
+    process.exit(1);
+  }
+  try {
+    await sh("gh", ["repo", "clone", forkFullName, destDir]);
+  } catch (err) {
+    try {
+      rmSync3(destDir, { recursive: true, force: true });
+    } catch {
+    }
+    console.error(`terminalhire claim: clone of ${forkFullName} failed. ${err.stderr || err.message || err}`);
+    process.exit(1);
+  }
+  try {
+    await sh("git", ["-C", destDir, "remote", "get-url", "upstream"]);
+  } catch {
+    try {
+      await sh("git", ["-C", destDir, "remote", "add", "upstream", `https://github.com/${claim.repoFullName}.git`]);
+    } catch {
+    }
+  }
+  const branch = startBranchFor(claim.repoFullName, issueNumber);
+  await sh("git", ["-C", destDir, "checkout", "-b", branch]);
+  const toplevel = await sh("git", ["-C", destDir, "rev-parse", "--show-toplevel"]);
+  claims.updateClaim(id, { worktreePath: toplevel, branch, state: "working" });
+  await requestIssueAssignment(claim, flags, ghUser);
+  console.log(`
+\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(`    terminalhire claim submit ${id}`);
+}
+async function cmdStartHere(claims, claim, flags = {}) {
+  let toplevel;
+  try {
+    toplevel = await sh("git", ["-C", process.cwd(), "rev-parse", "--show-toplevel"]);
+  } catch {
+    console.error("terminalhire claim: --here must be run inside a git repository.");
+    process.exit(1);
+  }
+  const remotesOut = await sh("git", ["-C", toplevel, "remote", "-v"]).catch(() => "");
+  const repos = new Set(
+    remotesOut.split("\n").map((l) => parseRepoFromRemote(l.split(/\s+/)[1])).filter(Boolean).map((r) => r.toLowerCase())
+  );
+  if (!repos.has(claim.repoFullName.toLowerCase())) {
+    console.error(
+      `terminalhire claim: --here expects a clone of ${claim.repoFullName}, but no remote here points there.
+  Use \`terminalhire claim start ${claim.id}\` (no --here) to fork + clone it into a fresh worktree.`
+    );
+    process.exit(1);
+  }
+  const dirty = await sh("git", ["-C", toplevel, "status", "--porcelain", "--untracked-files=no"]).catch(() => "");
+  if (dirty) {
+    console.error(
+      "terminalhire claim: --here needs a clean working tree (claim work must not mix with your current changes).\n  Commit or stash first, or use `terminalhire claim start` for an isolated worktree."
+    );
+    process.exit(1);
+  }
+  const issueNumber = (parseGitHubUrl(claim.issueUrl) || {}).number;
+  const branch = startBranchFor(claim.repoFullName, issueNumber);
+  await sh("git", ["-C", toplevel, "checkout", "-b", branch]);
+  claims.updateClaim(claim.id, { worktreePath: toplevel, branch, state: "working" });
+  await requestIssueAssignment(claim, flags);
+  console.log(`
+\u2713 Started here: ${claim.title}`);
+  console.log(`  worktree: ${toplevel}`);
+  console.log(`  branch:   ${branch}`);
+  console.log(`
+  When the work is done:  terminalhire claim submit ${claim.id}`);
+}
 async function cmdSubmit(id, flags = {}) {
   const worktreeOverride = flags.worktree;
   const claims = await Promise.resolve().then(() => (init_claims(), claims_exports));
@@ -9376,10 +9625,10 @@ async function cmdSubmit(id, flags = {}) {
     console.error(`terminalhire claim: no claim with id '${id}'.`);
     process.exit(1);
   }
-  if (claim.state !== "ready") {
+  if (claim.state !== "working" && claim.state !== "ready") {
     console.error(
-      `terminalhire claim: ${id} is '${claim.state}', not 'ready'. Submit only runs after the review gate clears it:
-  terminalhire claim update ${id} ready`
+      `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}`
     );
     process.exit(1);
   }
@@ -9586,10 +9835,22 @@ async function cmdSubmit(id, flags = {}) {
     const issueNo = (parseGitHubUrl(claim.issueUrl) || {}).number;
     const contention = issueNo ? await listOpenPRsReferencingIssue(claim.repoFullName, issueNo) : null;
     if (contention && contention.total > 0) {
-      console.log(`  \u26A0 contention: ${contention.total} open PR(s) already reference this issue:`);
       const nowMs = Date.now();
+      console.log(`  \u26A0 contention: ${contention.total} open PR(s) already reference this issue:`);
       for (const pr of contention.prs) console.log(fmtContentionPr(pr, nowMs, false));
       console.log(CONTENTION_HINT);
+      const competing = selectCompetingPrs(contention.prs, ghUser);
+      if (competing.length > 0 && !flags["force-competing"]) {
+        console.error(
+          `
+terminalhire claim: refusing to submit \u2014 ${competing.length} open PR(s) by someone else already address ${claim.repoFullName}#${issueNo}:`
+        );
+        for (const pr of competing) console.error(fmtContentionPr(pr, nowMs, false));
+        console.error(
+          "\n  Opening a competing PR reads as low-effort duplication and burns maintainer goodwill.\n  Stand down, or add value on the existing PR instead (a review, a test, a comment).\n  If you are certain yours should still go up, re-run with --force-competing."
+        );
+        process.exit(1);
+      }
     }
   }
   let ok;
@@ -9971,6 +10232,9 @@ async function run() {
       case "record":
         await cmdRecord(positional[0], flags);
         break;
+      case "start":
+        await cmdStart(positional[0], flags);
+        break;
       case "list":
         await cmdList(active);
         break;
@@ -9990,7 +10254,7 @@ async function run() {
         await cmdRelease(positional[0]);
         break;
       default:
-        console.error(`terminalhire claim: unknown verb '${verb ?? ""}'. Expected: preview | record | attach | list | status | update | submit | release`);
+        console.error(`terminalhire claim: unknown verb '${verb ?? ""}'. Expected: preview | record | start | attach | list | status | update | submit | release`);
         process.exit(1);
     }
   } catch (err) {
@@ -10002,10 +10266,12 @@ export {
   AI_DISCLOSURE_NOTE,
   CLAIM_CONSENT_VERSION,
   backgroundEnableFailed,
+  buildAssignmentComment,
   buildSubmitBody,
   cmdRecord,
   countOpenPRsReferencingIssue,
   diffContention,
+  explicitForkConsent,
   findClaimableByShortRef,
   findClaimableInCache,
   fmtAge,
@@ -10021,7 +10287,10 @@ export {
   resolveSubmitWorktree,
   revokeFailureAction,
   run,
-  selectPushRemote
+  selectCompetingPrs,
+  selectPushRemote,
+  startBranchFor,
+  workDirFor
 };
 /*! Bundled license information:
 

package/dist/bin/jpi-dispatch.js

@@ -11035,10 +11035,12 @@ __export(jpi_claim_exports, {
   AI_DISCLOSURE_NOTE: () => AI_DISCLOSURE_NOTE,
   CLAIM_CONSENT_VERSION: () => CLAIM_CONSENT_VERSION,
   backgroundEnableFailed: () => backgroundEnableFailed,
+  buildAssignmentComment: () => buildAssignmentComment,
   buildSubmitBody: () => buildSubmitBody,
   cmdRecord: () => cmdRecord,
   countOpenPRsReferencingIssue: () => countOpenPRsReferencingIssue,
   diffContention: () => diffContention,
+  explicitForkConsent: () => explicitForkConsent,
   findClaimableByShortRef: () => findClaimableByShortRef,
   findClaimableInCache: () => findClaimableInCache,
   fmtAge: () => fmtAge,
@@ -11054,7 +11056,10 @@ __export(jpi_claim_exports, {
   resolveSubmitWorktree: () => resolveSubmitWorktree,
   revokeFailureAction: () => revokeFailureAction,
   run: () => run7,
-  selectPushRemote: () => selectPushRemote
+  selectCompetingPrs: () => selectCompetingPrs,
+  selectPushRemote: () => selectPushRemote,
+  startBranchFor: () => startBranchFor,
+  workDirFor: () => workDirFor
 });
 import { readFileSync as readFileSync17, writeFileSync as writeFileSync11, mkdirSync as mkdirSync11, existsSync as existsSync10, rmSync as rmSync4 } from "fs";
 import { join as join17 } from "path";
@@ -11285,6 +11290,10 @@ ${p.body ?? ""}`)) {
   }
   return matched;
 }
+function selectCompetingPrs(prs, selfLogin) {
+  if (!Array.isArray(prs)) return [];
+  return prs.filter((pr) => pr && pr.author !== selfLogin);
+}
 async function listOpenPRsReferencingIssue(repoFullName, issueNumber) {
   try {
     const res = await fetch(`${GH_API2}/repos/${repoFullName}/pulls?state=open&per_page=100`, {
@@ -11350,6 +11359,65 @@ async function fetchIssue(repoFullName, issueNumber) {
     return null;
   }
 }
+function buildAssignmentComment(repoFullName) {
+  const usesTakeBot = TAKE_BOT_REPOS.has(repoFullName.toLowerCase());
+  const body = usesTakeBot ? "/take" : `I'd like to work on this \u2014 could I be assigned? Thanks!
+
+${ASSIGNMENT_MARKER}`;
+  return { usesTakeBot, body };
+}
+async function hasPriorAssignmentRequest(repoFullName, issueNumber, login) {
+  try {
+    const res = await fetch(
+      `${GH_API2}/repos/${repoFullName}/issues/${issueNumber}/comments?per_page=100&sort=created&direction=desc`,
+      { headers: GH_HEADERS2, signal: AbortSignal.timeout(1e4) }
+    );
+    if (!res.ok) return false;
+    const comments = await res.json();
+    if (!Array.isArray(comments)) return false;
+    return comments.some(
+      (c) => c && c.user && c.user.login === login && typeof c.body === "string" && c.body.includes(ASSIGNMENT_MARKER)
+    );
+  } catch {
+    return false;
+  }
+}
+async function requestIssueAssignment(claim, flags = {}, ghUser) {
+  if (flags["no-assign"]) {
+    console.log("  (--no-assign \u2014 skipping the assignment request; request it manually before working)");
+    return;
+  }
+  const parsed = parseGitHubUrl(claim.issueUrl);
+  if (!parsed) return;
+  const { repoFullName, number: number3 } = parsed;
+  let login = ghUser;
+  if (!login) {
+    try {
+      login = await sh("gh", ["api", "user", "-q", ".login"]);
+    } catch {
+      console.log("  (assignment not requested: 'gh' not authenticated \u2014 comment on the issue manually before working)");
+      return;
+    }
+  }
+  const issue2 = await fetchIssue(repoFullName, number3);
+  if (issue2 && issue2.assignees.includes(login)) {
+    console.log(`  \u2713 Already assigned to @${login} on ${repoFullName}#${number3}.`);
+    return;
+  }
+  const { usesTakeBot, body } = buildAssignmentComment(repoFullName);
+  if (!usesTakeBot && await hasPriorAssignmentRequest(repoFullName, number3, login)) {
+    console.log(`  \u2713 Assignment already requested on ${repoFullName}#${number3}.`);
+    return;
+  }
+  try {
+    await sh("gh", ["issue", "comment", String(number3), "--repo", repoFullName, "--body", body]);
+    console.log(
+      usesTakeBot ? `  \u2713 Requested assignment via /take on ${repoFullName}#${number3}.` : `  \u2713 Requested assignment on ${repoFullName}#${number3}.`
+    );
+  } catch (err) {
+    console.log(`  (could not post the assignment request: ${err.stderr || err.message || err} \u2014 do it manually before working)`);
+  }
+}
 async function pollPR(prUrl) {
   const p = parseGitHubUrl(prUrl);
   if (!p) return null;
@@ -11565,10 +11633,19 @@ terminalhire claim: refusing to record \u2014 read ${b.repoFullName}'s contribut
   console.log("   \u2022 MUST NOT `git push` or `gh pr` \u2014 pushing happens only via `terminalhire submit`");
   console.log("   \u2022 clone + static analysis + patch only; NO test/build execution without explicit approval");
   console.log("   \u2022 no access to ~/.terminalhire (the executor never needs your profile)");
-  console.log("\n  Next:");
-  console.log("   1. record the worktree:  terminalhire claim attach " + claim.id + " --worktree <path> --branch <branch>");
-  console.log("   2. do the work + review, then mark it cleared:  terminalhire claim update " + claim.id + " ready");
-  console.log("   3. publish (pushes to your fork + opens the PR):  terminalhire claim submit " + claim.id);
+  console.log("\n  Next \u2014 start work (forks + clones into an isolated worktree; your terminal stays put):");
+  console.log("    terminalhire claim start " + claim.id);
+  console.log("  Then publish when it is done (the only step that pushes + opens the PR):");
+  console.log("    terminalhire claim submit " + claim.id);
+  if (flags.start) {
+    await cmdStart(claim.id, { start: true });
+  } else if (process.stdin.isTTY && !flags["no-start"]) {
+    const go = await confirm(`
+  Fork ${claim.repoFullName} and start now? (y/N) `);
+    if (go) await cmdStart(claim.id, { start: true });
+    else console.log(`
+  Saved. Start anytime:  terminalhire claim start ${claim.id}`);
+  }
 }
 async function cmdPreview(arg, { json } = {}) {
   if (!arg) {
@@ -11765,6 +11842,181 @@ async function cmdAttach(id, worktree, branch) {
   claims.updateClaim(id, { worktreePath: toplevel, branch });
   console.log(`Attached ${id}: worktree=${toplevel} branch=${branch}`);
 }
+function workDirFor(repoFullName, issueNumber) {
+  const [owner, repo] = String(repoFullName).split("/");
+  const suffix = issueNumber ? `-${issueNumber}` : "";
+  return join17(homedir15(), "terminalhire", "work", `${owner}-${repo}${suffix}`);
+}
+function startBranchFor(repoFullName, issueNumber) {
+  const repo = String(repoFullName).split("/")[1] || "claim";
+  return `th/${repo}-${issueNumber || "work"}`;
+}
+function explicitForkConsent(flags = {}) {
+  return Boolean(flags.start) || Boolean(flags.fork);
+}
+async function ensureForkExists(repoFullName, ghUser) {
+  const repoShort = repoFullName.split("/")[1];
+  const forkFullName = `${ghUser}/${repoShort}`;
+  await sh("gh", ["repo", "fork", repoFullName, "--clone=false"]);
+  let isFork = false;
+  try {
+    isFork = await sh("gh", ["api", `repos/${forkFullName}`, "--jq", ".fork"]) === "true";
+  } catch {
+    isFork = false;
+  }
+  if (!isFork) throw new Error(`fork ${forkFullName} created but could not be verified as a fork`);
+  return forkFullName;
+}
+async function cmdStart(id, flags = {}) {
+  const claims = await Promise.resolve().then(() => (init_claims(), claims_exports));
+  if (!id) {
+    const startable = claims.listClaims({ active: true }).filter((c) => c.state === "claimed");
+    if (startable.length === 0) {
+      console.log("No claims ready to start. Claim one first:  terminalhire claim <ref>");
+      return;
+    }
+    console.log(`
+${startable.length} claim${startable.length === 1 ? "" : "s"} ready to start:
+`);
+    for (const c of startable) {
+      console.log(`  ${c.title}`);
+      console.log(`    terminalhire claim start ${c.id}`);
+    }
+    console.log("\nRun the command under the one you want to start.");
+    return;
+  }
+  const claim = claims.findClaim(id);
+  if (!claim) {
+    console.error(`terminalhire claim: no claim with id '${id}'.`);
+    process.exit(1);
+  }
+  if (claim.worktreePath) {
+    let stillThere = false;
+    try {
+      stillThere = await sh("git", ["-C", claim.worktreePath, "rev-parse", "--show-toplevel"]) === claim.worktreePath;
+    } catch {
+      stillThere = false;
+    }
+    if (stillThere) {
+      console.log("Already started \u2014 your worktree is ready (your terminal stays put):");
+      console.log(`  cd ${claim.worktreePath}`);
+      if (claim.branch) console.log(`  branch: ${claim.branch}`);
+      console.log(`
+When it's done:  terminalhire claim submit ${id}`);
+      return;
+    }
+  }
+  if (flags.here) {
+    await cmdStartHere(claims, claim, flags);
+    return;
+  }
+  let ghUser;
+  try {
+    ghUser = await sh("gh", ["api", "user", "-q", ".login"]);
+  } catch {
+    console.error("terminalhire claim: 'gh' CLI not available or not authenticated. Run 'gh auth login'.");
+    process.exit(1);
+  }
+  let consented = explicitForkConsent(flags);
+  if (!consented && process.stdin.isTTY) {
+    consented = await confirm(`
+  Fork ${claim.repoFullName} to @${ghUser} and clone it to start? (y/N) `);
+  }
+  if (!consented) {
+    console.error(
+      `
+terminalhire claim: not started \u2014 starting forks ${claim.repoFullName} to your GitHub account (a network write).
+  Re-run in a terminal to confirm interactively, or pass --fork to consent non-interactively.`
+    );
+    process.exit(1);
+  }
+  const issueNumber = (parseGitHubUrl(claim.issueUrl) || {}).number;
+  const destDir = workDirFor(claim.repoFullName, issueNumber);
+  if (existsSync10(destDir)) {
+    console.error(
+      `terminalhire claim: ${destDir} already exists \u2014 refusing to clobber it.
+  Remove it and retry, or attach it: terminalhire claim attach ${id} --worktree ${destDir} --branch <branch>`
+    );
+    process.exit(1);
+  }
+  mkdirSync11(join17(homedir15(), "terminalhire", "work"), { recursive: true });
+  let forkFullName;
+  try {
+    forkFullName = await ensureForkExists(claim.repoFullName, ghUser);
+  } catch (err) {
+    console.error(`terminalhire claim: could not create your fork of ${claim.repoFullName}. ${err.message ?? err}`);
+    process.exit(1);
+  }
+  try {
+    await sh("gh", ["repo", "clone", forkFullName, destDir]);
+  } catch (err) {
+    try {
+      rmSync4(destDir, { recursive: true, force: true });
+    } catch {
+    }
+    console.error(`terminalhire claim: clone of ${forkFullName} failed. ${err.stderr || err.message || err}`);
+    process.exit(1);
+  }
+  try {
+    await sh("git", ["-C", destDir, "remote", "get-url", "upstream"]);
+  } catch {
+    try {
+      await sh("git", ["-C", destDir, "remote", "add", "upstream", `https://github.com/${claim.repoFullName}.git`]);
+    } catch {
+    }
+  }
+  const branch = startBranchFor(claim.repoFullName, issueNumber);
+  await sh("git", ["-C", destDir, "checkout", "-b", branch]);
+  const toplevel = await sh("git", ["-C", destDir, "rev-parse", "--show-toplevel"]);
+  claims.updateClaim(id, { worktreePath: toplevel, branch, state: "working" });
+  await requestIssueAssignment(claim, flags, ghUser);
+  console.log(`
+\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(`    terminalhire claim submit ${id}`);
+}
+async function cmdStartHere(claims, claim, flags = {}) {
+  let toplevel;
+  try {
+    toplevel = await sh("git", ["-C", process.cwd(), "rev-parse", "--show-toplevel"]);
+  } catch {
+    console.error("terminalhire claim: --here must be run inside a git repository.");
+    process.exit(1);
+  }
+  const remotesOut = await sh("git", ["-C", toplevel, "remote", "-v"]).catch(() => "");
+  const repos = new Set(
+    remotesOut.split("\n").map((l) => parseRepoFromRemote(l.split(/\s+/)[1])).filter(Boolean).map((r) => r.toLowerCase())
+  );
+  if (!repos.has(claim.repoFullName.toLowerCase())) {
+    console.error(
+      `terminalhire claim: --here expects a clone of ${claim.repoFullName}, but no remote here points there.
+  Use \`terminalhire claim start ${claim.id}\` (no --here) to fork + clone it into a fresh worktree.`
+    );
+    process.exit(1);
+  }
+  const dirty = await sh("git", ["-C", toplevel, "status", "--porcelain", "--untracked-files=no"]).catch(() => "");
+  if (dirty) {
+    console.error(
+      "terminalhire claim: --here needs a clean working tree (claim work must not mix with your current changes).\n  Commit or stash first, or use `terminalhire claim start` for an isolated worktree."
+    );
+    process.exit(1);
+  }
+  const issueNumber = (parseGitHubUrl(claim.issueUrl) || {}).number;
+  const branch = startBranchFor(claim.repoFullName, issueNumber);
+  await sh("git", ["-C", toplevel, "checkout", "-b", branch]);
+  claims.updateClaim(claim.id, { worktreePath: toplevel, branch, state: "working" });
+  await requestIssueAssignment(claim, flags);
+  console.log(`
+\u2713 Started here: ${claim.title}`);
+  console.log(`  worktree: ${toplevel}`);
+  console.log(`  branch:   ${branch}`);
+  console.log(`
+  When the work is done:  terminalhire claim submit ${claim.id}`);
+}
 async function cmdSubmit(id, flags = {}) {
   const worktreeOverride = flags.worktree;
   const claims = await Promise.resolve().then(() => (init_claims(), claims_exports));
@@ -11779,10 +12031,10 @@ async function cmdSubmit(id, flags = {}) {
     console.error(`terminalhire claim: no claim with id '${id}'.`);
     process.exit(1);
   }
-  if (claim.state !== "ready") {
+  if (claim.state !== "working" && claim.state !== "ready") {
     console.error(
-      `terminalhire claim: ${id} is '${claim.state}', not 'ready'. Submit only runs after the review gate clears it:
-  terminalhire claim update ${id} ready`
+      `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}`
     );
     process.exit(1);
   }
@@ -11989,10 +12241,22 @@ async function cmdSubmit(id, flags = {}) {
     const issueNo = (parseGitHubUrl(claim.issueUrl) || {}).number;
     const contention = issueNo ? await listOpenPRsReferencingIssue(claim.repoFullName, issueNo) : null;
     if (contention && contention.total > 0) {
-      console.log(`  \u26A0 contention: ${contention.total} open PR(s) already reference this issue:`);
       const nowMs = Date.now();
+      console.log(`  \u26A0 contention: ${contention.total} open PR(s) already reference this issue:`);
       for (const pr of contention.prs) console.log(fmtContentionPr(pr, nowMs, false));
       console.log(CONTENTION_HINT);
+      const competing = selectCompetingPrs(contention.prs, ghUser);
+      if (competing.length > 0 && !flags["force-competing"]) {
+        console.error(
+          `
+terminalhire claim: refusing to submit \u2014 ${competing.length} open PR(s) by someone else already address ${claim.repoFullName}#${issueNo}:`
+        );
+        for (const pr of competing) console.error(fmtContentionPr(pr, nowMs, false));
+        console.error(
+          "\n  Opening a competing PR reads as low-effort duplication and burns maintainer goodwill.\n  Stand down, or add value on the existing PR instead (a review, a test, a comment).\n  If you are certain yours should still go up, re-run with --force-competing."
+        );
+        process.exit(1);
+      }
     }
   }
   let ok;
@@ -12374,6 +12638,9 @@ async function run7() {
       case "record":
         await cmdRecord(positional[0], flags);
         break;
+      case "start":
+        await cmdStart(positional[0], flags);
+        break;
       case "list":
         await cmdList(active);
         break;
@@ -12393,7 +12660,7 @@ async function run7() {
         await cmdRelease(positional[0]);
         break;
       default:
-        console.error(`terminalhire claim: unknown verb '${verb ?? ""}'. Expected: preview | record | attach | list | status | update | submit | release`);
+        console.error(`terminalhire claim: unknown verb '${verb ?? ""}'. Expected: preview | record | start | attach | list | status | update | submit | release`);
         process.exit(1);
     }
   } catch (err) {
@@ -12401,7 +12668,7 @@ async function run7() {
     process.exit(1);
   }
 }
-var TERMINALHIRE_DIR13, INDEX_CACHE_FILE5, CLAIM_PUSH_MARKER, API_URL6, CLAIM_SYNC_BASE2, CLAIM_CONSENT_VERSION, CLAIM_POLL_INTERVAL_MS, CLAIM_POLL_TIMEOUT_MS, GH_API2, GH_HEADERS2, CONTENTION_HINT, AI_DISCLOSURE_NOTE, pExecFile, VALUE_FLAGS;
+var TERMINALHIRE_DIR13, INDEX_CACHE_FILE5, CLAIM_PUSH_MARKER, API_URL6, CLAIM_SYNC_BASE2, 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, TAKE_BOT_REPOS;
 var init_jpi_claim = __esm({
   "bin/jpi-claim.js"() {
     "use strict";
@@ -12423,6 +12690,8 @@ var init_jpi_claim = __esm({
     AI_DISCLOSURE_NOTE = "---\nThis contribution was developed with AI assistance via [terminalhire](https://terminalhire.com). The author has reviewed the change and takes responsibility for its content.";
     pExecFile = promisify(execFile);
     VALUE_FLAGS = /* @__PURE__ */ new Set(["worktree", "branch", "body-file", "title"]);
+    ASSIGNMENT_MARKER = "<!-- terminalhire:assignment-request -->";
+    TAKE_BOT_REPOS = /* @__PURE__ */ new Set(["paradedb/paradedb"]);
   }
 });
 
@@ -42869,6 +43138,7 @@ if (!firstArg || firstArg === "help" || firstArg === "--help" || firstArg === "-
   console.log("  terminalhire bounties --priced              Only bounties with a known $ amount");
   console.log("  terminalhire contribute                     Open issues where a merged PR counts toward your r\xE9sum\xE9");
   console.log("  terminalhire claim record <id|issueUrl>     Claim a bounty locally + print the executor brief");
+  console.log("  terminalhire claim start [<id>]             Fork + clone + branch into an isolated worktree (never cd's you)");
   console.log("  terminalhire claim list [--active]          List your claims + accepted-PR rate");
   console.log("  terminalhire claim status [<id>]            Poll source PR merge state (updates the metric)");
   console.log("  terminalhire claim --push                   Opt-in: show your claims on your dashboard (typed-yes + browser confirm)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminalhire",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "description": "Local-first job matching for developers — ambient job matches in the Claude Code spinner. Matching runs on your machine; your profile never leaves it.",
   "repository": {
     "type": "git",