terminalhire 0.26.1 → 0.27.0

package/dist/bin/jpi-claim.js

@@ -8796,6 +8796,9 @@ function looksLikeShortRef(arg) {
 function isVerblessShortRefClaim(verb, positional) {
   return looksLikeShortRef(verb) && positional.length === 0;
 }
+function isStrayArgShortRefClaim(verb, positional) {
+  return looksLikeShortRef(verb) && positional.length > 0;
+}
 function findClaimableByShortRef(ref) {
   try {
     return findByShortRefInPool(readClaimablePool(), ref);
@@ -9159,10 +9162,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) {
@@ -9359,6 +9371,179 @@ 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);
+    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" });
+  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) {
+  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" });
+  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));
@@ -9373,10 +9558,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);
   }
@@ -9954,6 +10139,12 @@ async function run() {
     await cmdRecord(verb, flags);
     return;
   }
+  if (isStrayArgShortRefClaim(verb, positional)) {
+    console.error(
+      `terminalhire claim: '${verb}' is a short ref and takes no extra arguments (got: ${positional.join(" ")}). Did you mean \`terminalhire claim ${verb}\`?`
+    );
+    process.exit(1);
+  }
   try {
     switch (verb) {
       case "preview":
@@ -9962,6 +10153,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;
@@ -9981,7 +10175,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) {
@@ -9997,11 +10191,13 @@ export {
   cmdRecord,
   countOpenPRsReferencingIssue,
   diffContention,
+  explicitForkConsent,
   findClaimableByShortRef,
   findClaimableInCache,
   fmtAge,
   fmtContestedWarning,
   isContested,
+  isStrayArgShortRefClaim,
   isVerblessShortRefClaim,
   listOpenPRsReferencingIssue,
   matchReferencingPrs,
@@ -10011,7 +10207,9 @@ export {
   resolveSubmitWorktree,
   revokeFailureAction,
   run,
-  selectPushRemote
+  selectPushRemote,
+  startBranchFor,
+  workDirFor
 };
 /*! Bundled license information:
 

package/dist/bin/jpi-dispatch.js

@@ -11039,11 +11039,13 @@ __export(jpi_claim_exports, {
   cmdRecord: () => cmdRecord,
   countOpenPRsReferencingIssue: () => countOpenPRsReferencingIssue,
   diffContention: () => diffContention,
+  explicitForkConsent: () => explicitForkConsent,
   findClaimableByShortRef: () => findClaimableByShortRef,
   findClaimableInCache: () => findClaimableInCache,
   fmtAge: () => fmtAge,
   fmtContestedWarning: () => fmtContestedWarning,
   isContested: () => isContested,
+  isStrayArgShortRefClaim: () => isStrayArgShortRefClaim,
   isVerblessShortRefClaim: () => isVerblessShortRefClaim,
   listOpenPRsReferencingIssue: () => listOpenPRsReferencingIssue,
   matchReferencingPrs: () => matchReferencingPrs,
@@ -11053,7 +11055,9 @@ __export(jpi_claim_exports, {
   resolveSubmitWorktree: () => resolveSubmitWorktree,
   revokeFailureAction: () => revokeFailureAction,
   run: () => run7,
-  selectPushRemote: () => selectPushRemote
+  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";
@@ -11198,6 +11202,9 @@ function looksLikeShortRef(arg) {
 function isVerblessShortRefClaim(verb, positional) {
   return looksLikeShortRef(verb) && positional.length === 0;
 }
+function isStrayArgShortRefClaim(verb, positional) {
+  return looksLikeShortRef(verb) && positional.length > 0;
+}
 function findClaimableByShortRef(ref) {
   try {
     return findByShortRefInPool(readClaimablePool(), ref);
@@ -11561,10 +11568,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) {
@@ -11761,6 +11777,179 @@ 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);
+    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" });
+  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) {
+  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" });
+  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));
@@ -11775,10 +11964,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);
   }
@@ -12356,6 +12545,12 @@ async function run7() {
     await cmdRecord(verb, flags);
     return;
   }
+  if (isStrayArgShortRefClaim(verb, positional)) {
+    console.error(
+      `terminalhire claim: '${verb}' is a short ref and takes no extra arguments (got: ${positional.join(" ")}). Did you mean \`terminalhire claim ${verb}\`?`
+    );
+    process.exit(1);
+  }
   try {
     switch (verb) {
       case "preview":
@@ -12364,6 +12559,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;
@@ -12383,7 +12581,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) {
@@ -42859,6 +43057,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.1",
+  "version": "0.27.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",