@gredescerber/agent-crew 0.0.0-stage → 0.6.0

package/src/core/guard.js

@@ -0,0 +1,273 @@
+// crew-guard: PR rules without a human "approve button". Pure functions, no network (tests run them).
+//
+// A human does not approve every PR. Instead, automatically:
+//   1. Agents never change agent rules and CI (PROTECTED_PATHS): a PR touching them will not pass.
+//      Only the harness developer changes them (harness update), merging past protection as admin.
+//   2. Acceptance tests: new ones may be added; changing/deleting existing ones is allowed only if
+//      the PR's task (Closes #N) explicitly lists those files in the "Changes acceptance" section.
+//      Such a task is written by the planner/analyst (usually from human feedback), not by a builder.
+//   3. Review is done by an agent: a crew:review marker from ANOTHER agent on the PR's current commit
+//      (by default from another vendor; if there is none for longer than fallback_minutes, from any other agent).
+//
+// Limitation: agents work under human accounts, so this does not stop a deliberate agent forging a marker.
+// The goal is to catch laziness and mistakes (weakened a test, "fixed" CI, approved itself).
+
+import { isTrustedComment } from './issues.js';
+
+/** Agent rules and CI files: agents do not change them. */
+export const PROTECTED_PATHS = ['crew.config.json', '.github/', 'AGENTS.md', 'CLAUDE.md', 'agents/', 'events/'];
+export const ACCEPTANCE_DIR = 'tests/acceptance/';
+/** Tests from a tests task (tests_for), until a code task moves them. CI does not run them. */
+export const PENDING_DIR = 'tests/pending/';
+
+/** Rename tests/pending/... -> tests/acceptance/... without a single changed line. */
+export function isPureMove(f = {}) {
+  const changes = Number.isFinite(f.changes) ? f.changes : (f.additions ?? 0) + (f.deletions ?? 0);
+  return (
+    f.status === 'renamed' &&
+    !!f.previous_filename &&
+    norm(f.previous_filename).startsWith(PENDING_DIR) &&
+    norm(f.filename).startsWith(ACCEPTANCE_DIR) &&
+    (Number.isFinite(f.changes) || Number.isFinite(f.additions) || Number.isFinite(f.deletions)) &&
+    changes === 0
+  );
+}
+
+/** Markers of a task from the issue body: { taskId, testsFor, testsIssue }. */
+export function taskMarkers(issueBody = '') {
+  const pick = (kind, key) => new RegExp(`<!-- (?:crew|hk):${kind}\\b[^>]*?\\b${key}=(\\S+?)[\\s>]`).exec(issueBody ?? '')?.[1] ?? null;
+  return { taskId: pick('task', 'id'), testsFor: pick('tests-for', 'task'), testsIssue: Number(pick('tests', 'issue')) || null };
+}
+export const ACCEPTANCE_SECTION = 'Changes acceptance';
+export const REVIEW_MODES = ['other-vendor', 'other-agent'];
+export const GUARD_CONTEXT = 'crew-guard';
+
+const norm = (p) => String(p).replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\//, '');
+
+export function isProtected(path) {
+  const p = norm(path);
+  return PROTECTED_PATHS.some((x) => (x.endsWith('/') ? p.startsWith(x) : p === x));
+}
+
+/** Review settings from crew.config.json -> review. Default: other-vendor when there is more than one host. */
+export function reviewPolicy(config = {}) {
+  const r = config.review ?? {};
+  const multi = (config.hosts ?? []).length > 1;
+  return {
+    require: REVIEW_MODES.includes(r.require) ? r.require : multi ? 'other-vendor' : 'other-agent',
+    approvals: Number.isInteger(r.approvals) && r.approvals >= 0 ? r.approvals : 1,
+    approvals_high: Number.isInteger(r.approvals_high) && r.approvals_high >= 0 ? r.approvals_high : 1,
+    fallback_minutes: Number.isFinite(r.fallback_minutes) && r.fallback_minutes >= 0 ? r.fallback_minutes : 30,
+  };
+}
+
+/** Task number from the PR body (Closes/Fixes/Resolves #N). */
+export function linkedIssue(body = '') {
+  return Number(/\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?) #(\d+)/i.exec(body ?? '')?.[1]) || null;
+}
+
+/** Author agent from the PR body (crew pr open writes **Agent:** `codex/x`). */
+export function authorAgent(body = '') {
+  return /\*\*Agent:\*\*\s*`([^`]+)`/.exec(body ?? '')?.[1] ?? null;
+}
+
+/** Vendor from an agent id: claude/opus@petya -> claude. */
+export const vendorOf = (agent) => String(agent ?? '').split(/[/@]/)[0] || null;
+
+/**
+ * Which existing acceptance tests the task allows changing: the "Changes acceptance" section of the issue body.
+ * Lines with paths inside tests/acceptance/; `dir/**` means the whole folder. Everything else is ignored.
+ */
+export function allowedAcceptanceChanges(issueBody = '') {
+  const lines = String(issueBody ?? '').split(/\r?\n/);
+  const start = lines.findIndex((l) => /^#{2,4}\s+/.test(l) && l.replace(/^#+\s+/, '').trim() === ACCEPTANCE_SECTION);
+  if (start < 0) return [];
+  const out = [];
+  for (const l of lines.slice(start + 1)) {
+    if (/^#{1,4}\s+/.test(l)) break;
+    for (const m of l.matchAll(/(?:^|[\s`,(])((?:\.\/)?tests\/acceptance\/[^\s`,)]+)/g)) out.push(norm(m[1]));
+  }
+  return [...new Set(out)];
+}
+
+const covered = (path, allowed) =>
+  allowed.some((a) => (a.endsWith('/**') ? path.startsWith(a.slice(0, -2)) : a.endsWith('/') ? path.startsWith(a) : path === a));
+
+/**
+ * Changed PR files (as in GitHub API pulls/N/files: filename, status, previous_filename)
+ * -> violations of protected paths and acceptance tests.
+ */
+export function fileViolations(files = [], { allowedAcceptance = [] } = {}) {
+  const protectedHits = [];
+  const acceptanceHits = [];
+  for (const f of files) {
+    const paths = [f.filename, f.previous_filename].filter(Boolean).map(norm);
+    if (paths.some(isProtected)) protectedHits.push(norm(f.filename));
+    // Moving tests written by another agent from tests/pending/ to tests/acceptance/ unchanged is allowed.
+    if (isPureMove(f)) continue;
+    // tests/pending/ (tests from a tests task) are frozen the same way as tests/acceptance/.
+    const prevPending = f.previous_filename && norm(f.previous_filename).startsWith(PENDING_DIR);
+    if ((f.status !== 'added' && norm(f.filename).startsWith(PENDING_DIR)) || prevPending) {
+      acceptanceHits.push(norm(f.previous_filename ?? f.filename));
+      continue;
+    }
+    // new files in tests/acceptance are allowed; changing/deleting/renaming an existing one only by task
+    const touchesExisting =
+      (f.status !== 'added' && norm(f.filename).startsWith(ACCEPTANCE_DIR)) ||
+      (f.previous_filename && norm(f.previous_filename).startsWith(ACCEPTANCE_DIR));
+    if (touchesExisting) {
+      const target = norm(f.previous_filename ?? f.filename);
+      if (!covered(target, allowedAcceptance)) acceptanceHits.push(target);
+    }
+  }
+  return { protectedHits: [...new Set(protectedHits)], acceptanceHits: [...new Set(acceptanceHits)] };
+}
+
+/**
+ * Review markers: <!-- crew:review verdict=approve|changes agent=<id> sha=<commit> -->.
+ * The last verdict of each agent is taken; only verdicts on the current head count.
+ */
+export function reviewState(comments = [], { headSha, author, policy, prCreatedAt, now = Date.now() }) {
+  const latest = new Map();
+  for (const c of comments) {
+    // in a public repo anyone can comment: review markers only count from repo members
+    if (!isTrustedComment(c)) continue;
+    for (const m of String(c.body ?? '').matchAll(/<!-- (?:crew|hk):review((?: \w+=\S+)*) -->/g)) {
+      const f = Object.fromEntries([...m[1].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
+      if (!f.agent || !f.verdict || !f.sha) continue;
+      latest.set(f.agent, { agent: f.agent, verdict: f.verdict, sha: f.sha, at: c.createdAt });
+    }
+  }
+  const onHead = [...latest.values()].filter((r) => headSha && r.sha.length >= 7 && headSha.startsWith(r.sha));
+  const notAuthor = onHead.filter((r) => r.agent !== author);
+  const otherVendor = notAuthor.filter((r) => vendorOf(r.agent) !== vendorOf(author));
+  const created = Date.parse(prCreatedAt ?? '');
+  const fallback = policy.require === 'other-vendor' && Number.isFinite(created) && now - created > policy.fallback_minutes * 60_000;
+  const eligible = policy.require === 'other-agent' || fallback ? notAuthor : otherVendor;
+  return {
+    approvals: eligible.filter((r) => r.verdict === 'approve').map((r) => r.agent),
+    changes: eligible.filter((r) => r.verdict === 'changes').map((r) => r.agent),
+    stale: [...latest.values()].filter((r) => !onHead.includes(r)).map((r) => r.agent),
+    self: onHead.some((r) => r.agent === author),
+    fallback,
+  };
+}
+
+/**
+ * PR summary -> { state: success|pending|failure, description (<=140 chars for the status), problems[] }.
+ * failure: a rule is violated (the agent must redo it); pending: all fine, waiting for an agent review.
+ */
+export function evaluateGuard({ files = [], body = '', issueBody = '', comments = [], commits = [], headSha, risk = 'med', createdAt, config = {}, now = Date.now(), pendingFiles = [] }) {
+  const problems = [];
+  const issue = linkedIssue(body);
+  if (!issue) problems.push({ rule: 'closes', message: 'the PR description has no "Closes #N": a PR must close a task' });
+
+  const noAgent = commits.filter((c) => !String(c.agent ?? '').trim()).map((c) => c.sha);
+  if (noAgent.length) {
+    problems.push({
+      rule: 'agent_trailer',
+      message: `commits without an Agent trailer: ${noAgent.map((sha) => sha.slice(0, 7)).join(', ')} (use crew commit)`,
+      commits: noAgent,
+    });
+  }
+
+  // Tests and code are by different agents: a tests task touches only its own tests/pending/<T>/ folder,
+  // a code task must move all those tests to tests/acceptance/ unchanged.
+  const tm = taskMarkers(issueBody);
+  if (tm.testsFor) {
+    const dir = `${PENDING_DIR}${tm.testsFor}/`;
+    const outside = files.map((f) => norm(f.filename)).filter((p) => !p.startsWith(dir));
+    if (outside.length) {
+      problems.push({ rule: 'tests_task_scope', message: `the tests task only changes ${dir}, but the PR touches: ${outside.join(', ')}`, files: outside });
+    }
+  }
+  if (pendingFiles.length) {
+    const moved = new Set(files.filter(isPureMove).map((f) => norm(f.previous_filename)));
+    const left = pendingFiles.map(norm).filter((p) => !moved.has(p));
+    if (left.length) {
+      problems.push({
+        rule: 'pending_tests_not_moved',
+        message: `tests from the tests task were not moved to tests/acceptance/ unchanged: ${left.join(', ')} (git mv, no edits)`,
+        files: left,
+      });
+    }
+  }
+
+  const allowedAcceptance = allowedAcceptanceChanges(issueBody);
+  const { protectedHits, acceptanceHits } = fileViolations(files, { allowedAcceptance });
+  if (protectedHits.length) {
+    problems.push({
+      rule: 'protected_paths',
+      message: `the PR changes agent rules or CI (${protectedHits.join(', ')}): not allowed for agents; only the harness developer changes these`,
+      files: protectedHits,
+    });
+  }
+  if (acceptanceHits.length) {
+    problems.push({
+      rule: 'acceptance_changed',
+      message: `the PR changes existing acceptance tests (${acceptanceHits.join(', ')}), but task #${issue ?? '?'} does not allow it (section "${ACCEPTANCE_SECTION}")`,
+      files: acceptanceHits,
+    });
+  }
+
+  const policy = reviewPolicy(config);
+  const author = authorAgent(body);
+  if (!author) {
+    problems.push({
+      rule: 'not_crew_pr',
+      message: 'the PR description has no **Agent:** line: the PR was not opened via crew pr open (without crew check and a known author the review cannot count)',
+    });
+  }
+  const need = risk === 'high' ? policy.approvals_high : policy.approvals;
+  const review = reviewState(comments, { headSha, author, policy, prCreatedAt: createdAt, now });
+  if (review.changes.length) {
+    problems.push({ rule: 'changes_requested', message: `reviewer requests changes: ${review.changes.join(', ')}` });
+  }
+
+  // A human may waive "paperwork" rules for this commit (crew pr waive): a PR made outside crew (cloud session,
+  // plain git). Protected files, acceptance tests and the review itself can never be waived.
+  const waivers = waivedRules(comments, headSha);
+  const waived = problems.filter((p) => WAIVABLE.includes(p.rule) && waivers.has(p.rule)).map((p) => p.rule);
+  for (const r of waived) problems.splice(problems.findIndex((p) => p.rule === r), 1);
+
+  const fail = problems.length > 0;
+  const reviewed = review.approvals.length >= need;
+  const state = fail ? 'failure' : reviewed ? 'success' : 'pending';
+  const who = policy.require === 'other-vendor' && !review.fallback ? 'an agent from another vendor' : 'another agent';
+  const description = (fail
+    ? problems.map((p) => p.rule).join(', ')
+    : reviewed
+      ? `ok: review ${review.approvals.join(', ') || 'not required'}`
+      : `waiting for review by ${who}: ${review.approvals.length}/${need}`) + (waived.length && !fail ? ` (waived: ${waived.join(', ')})` : '');
+  return {
+    state,
+    description: description.slice(0, 140),
+    problems,
+    waived,
+    issue,
+    author,
+    review: { ...review, need, require: policy.require },
+    allowed_acceptance: allowedAcceptance,
+  };
+}
+
+/** Rules a human can waive with crew pr waive (paperwork only). */
+export const WAIVABLE = ['closes', 'agent_trailer', 'not_crew_pr'];
+
+/** Waived rules for this head commit: <!-- crew:waive rule=<r> sha=<head> --> in trusted, non-bot comments. */
+export function waivedRules(comments = [], headSha = '') {
+  const out = new Set();
+  for (const c of comments) {
+    if (!isTrustedComment(c) || /\[bot\]$|^github-actions$/.test(c.author?.login ?? '')) continue;
+    for (const m of String(c.body ?? '').matchAll(/<!-- crew:waive((?: \w+=\S+)*) -->/g)) {
+      const f = Object.fromEntries([...m[1].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
+      if (f.rule && f.sha && f.sha.length >= 7 && String(headSha).startsWith(f.sha)) out.add(f.rule);
+    }
+  }
+  return out;
+}
+
+export const waiveMarker = ({ rule, sha }) => `<!-- crew:waive rule=${rule} sha=${sha} -->`;
+
+/** Review marker text for a comment. */
+export const reviewMarker = ({ verdict, agent, sha }) => `<!-- crew:review verdict=${verdict} agent=${agent} sha=${sha} -->`;

package/src/core/issues.js

@@ -0,0 +1,154 @@
+// Working with the task queue in GitHub Issues through the gh CLI.
+import { gh, ghJson } from './exec.js';
+
+// waiting: waits for dependencies (crew:after marker in the body); crew task promote moves it to ready.
+export const STATUS = ['ready', 'claimed', 'review', 'blocked', 'needs-spec', 'waiting', 'done'];
+export const TIERS = ['low', 'mid', 'high'];
+
+export const labelValue = (issue, prefix) =>
+  issue.labels.map((l) => l.name).find((n) => n.startsWith(prefix + ':'))?.slice(prefix.length + 1) ?? null;
+
+export function listIssues({ label, limit = 200 } = {}) {
+  const args = ['issue', 'list', '--state', 'open', '--limit', String(limit), '--json', 'number,title,labels,assignees,updatedAt'];
+  if (label) args.push('--label', label);
+  return ghJson(args) ?? [];
+}
+
+/** Emergency stop label: while such an issue is open, agents do not take tasks. */
+export const PAUSE_LABEL = 'crew:pause';
+
+/** Open issues with the crew:pause label (pure function over the list from listIssues). */
+export function pauseIssues(issues = []) {
+  return issues.filter(
+    (i) => (i.state ?? 'OPEN').toUpperCase() === 'OPEN' && (i.labels ?? []).some((l) => (l?.name ?? l) === PAUSE_LABEL),
+  );
+}
+
+/** Whether the emergency stop is on. Without an argument it asks GitHub; tests pass a list. */
+export function isPaused(issues = listIssues({ label: PAUSE_LABEL })) {
+  return pauseIssues(issues).length > 0;
+}
+
+export function viewIssue(n) {
+  return ghJson(['issue', 'view', String(n), '--json', 'number,title,labels,assignees,body,updatedAt,state,comments']);
+}
+
+export function setStatus(n, to, { from = [] } = {}) {
+  const args = ['issue', 'edit', String(n), '--add-label', `status:${to}`];
+  for (const f of from) if (f !== to) args.push('--remove-label', `status:${f}`);
+  gh(args);
+}
+
+export function comment(n, body) {
+  gh(['issue', 'comment', String(n), '--body', body]);
+}
+
+/** Machine-readable markers in comments: <!-- crew:claim agent=codex/x at=ISO --> */
+export const marker = (kind, fields) =>
+  `<!-- crew:${kind} ${Object.entries(fields).map(([k, v]) => `${k}=${v}`).join(' ')} -->`;
+
+/**
+ * Text from an agent/human (--note) into a comment: escapes HTML comments
+ * so a quoted marker in the note does not become a real marker.
+ */
+export const safeText = (s = '') => String(s ?? '').replace(/<!--/g, '&lt;!--').replace(/-->/g, '--&gt;');
+
+/** Repo members (write access) and the Actions bot. Markers from anyone else are ignored. */
+export const TRUSTED_ASSOCIATIONS = ['OWNER', 'MEMBER', 'COLLABORATOR'];
+const BOT_LOGINS = ['github-actions', 'github-actions[bot]'];
+
+/**
+ * Whether markers in a comment can be trusted. In a public repo anyone can comment;
+ * without this check an outsider could take a task from an agent (crew:release) or "approve" a PR (crew:review).
+ * A comment without author/authorAssociation fields (synthetic, in tests) is trusted.
+ */
+export function isTrustedComment(c = {}) {
+  if (!('authorAssociation' in c) && !c.author) return true;
+  if (BOT_LOGINS.includes(c.author?.login)) return true;
+  return TRUSTED_ASSOCIATIONS.includes(String(c.authorAssociation ?? '').toUpperCase());
+}
+
+export function parseMarkers(comments = [], { trustedOnly = true } = {}) {
+  const out = [];
+  for (const c of comments) {
+    if (trustedOnly && !isTrustedComment(c)) continue;
+    for (const m of (c.body ?? '').matchAll(/<!-- (?:crew|hk):(\w+)((?: \w+=\S+)*) -->/g)) {
+      const fields = Object.fromEntries([...m[2].matchAll(/(\w+)=(\S+)/g)].map((x) => [x[1], x[2]]));
+      out.push({ kind: m[1], ...fields, createdAt: c.createdAt, by: c.author?.login ?? null });
+    }
+  }
+  return out;
+}
+
+/** Who currently owns the task: the first claim after the last release. */
+export function currentOwner(comments) {
+  const ms = parseMarkers(comments);
+  let owner = null;
+  for (const m of ms) {
+    if (m.kind === 'release') owner = null;
+    else if (m.kind === 'claim' && !owner) owner = m;
+  }
+  return owner;
+}
+
+const markerTime = (m) => m?.createdAt ?? m?.at ?? null;
+
+/**
+ * Latest activity of the OWNER: their markers (claim, heartbeat, status) after their claim.
+ * Markers from other agents (e.g. the loser of a claim_conflict) do not extend the lease.
+ */
+export function ownerActivityAt(comments, owner) {
+  if (!owner) return null;
+  const ms = parseMarkers(comments);
+  const start = ms.findIndex((m) => m.kind === 'claim' && m.agent === owner.agent && m.at === owner.at);
+  let last = markerTime(owner);
+  for (const m of ms.slice(Math.max(start, 0))) if (m.agent === owner.agent && m.kind !== 'release') last = markerTime(m) ?? last;
+  return last;
+}
+
+/**
+ * Owner and whether their lease went stale (pure function).
+ * -> { owner, lastActivityAt, stale }; with no owner stale = false.
+ */
+export function ownerState(comments, { lastCommitAt = null, now = Date.now(), leaseMinutes }) {
+  const owner = currentOwner(comments);
+  if (!owner) return { owner: null, lastActivityAt: null, stale: false };
+  const lastActivityAt = ownerActivityAt(comments, owner);
+  return { owner, lastActivityAt, stale: isStale({ lastMarkerAt: lastActivityAt, lastCommitAt, now, leaseMinutes }) };
+}
+
+/** ISO string / Date / ms number -> ms or null. */
+const toMs = (x) => {
+  if (x === null || x === undefined || x === '') return null;
+  const t = x instanceof Date ? x.getTime() : typeof x === 'number' ? x : Date.parse(x);
+  return Number.isFinite(t) ? t : null;
+};
+
+/**
+ * Whether the task lease went stale (pure function, tests run it).
+ * Activity = the last crew marker in comments (if none, the issue's updatedAt)
+ * OR the last commit on the task branch origin/crew/<id>-*, whichever is fresher.
+ * So an agent that pushes but sends no heartbeat does not lose the task.
+ * If there is no date at all, it is not stale (we do not take a task blindly).
+ */
+export function isStale({ lastMarkerAt, issueUpdatedAt, lastCommitAt, now = Date.now(), leaseMinutes }) {
+  const times = [toMs(lastMarkerAt) ?? toMs(issueUpdatedAt), toMs(lastCommitAt)].filter((t) => t !== null);
+  if (!times.length) return false;
+  return toMs(now) - Math.max(...times) > leaseMinutes * 60_000;
+}
+
+export function tierAllows(workerTier, taskTier) {
+  return TIERS.indexOf(taskTier ?? 'mid') <= TIERS.indexOf(workerTier ?? 'high');
+}
+
+const CYRILLIC = {
+  '\u0430': 'a', '\u0431': 'b', '\u0432': 'v', '\u0433': 'g', '\u0434': 'd', '\u0435': 'e', '\u0451': 'yo', '\u0436': 'zh', '\u0437': 'z', '\u0438': 'i', '\u0439': 'y',
+  '\u043a': 'k', '\u043b': 'l', '\u043c': 'm', '\u043d': 'n', '\u043e': 'o', '\u043f': 'p', '\u0440': 'r', '\u0441': 's', '\u0442': 't', '\u0443': 'u', '\u0444': 'f',
+  '\u0445': 'kh', '\u0446': 'ts', '\u0447': 'ch', '\u0448': 'sh', '\u0449': 'shch', '\u044a': '', '\u044b': 'y', '\u044c': '', '\u044d': 'e', '\u044e': 'yu', '\u044f': 'ya',
+};
+
+export function slugify(title) {
+  const s = title.normalize('NFC').toLowerCase().replace(/[\u0430-\u044f\u0451]/g, (c) => CYRILLIC[c])
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40).replace(/-$/, '');
+  return s || 'task';
+}

package/src/core/lease.js

@@ -0,0 +1,48 @@
+// Task lease from inside working commands (crew check, crew commit, crew pr open).
+// 1) Renews the lease itself (heartbeat) so an agent working silently for a long time does not lose the task.
+// 2) Checks the task is still mine: if sweep returned it to the queue and another agent took it,
+//    committing and opening a PR is not allowed, otherwise two agents would open two PRs for one task.
+import { viewIssue, comment, currentOwner, ownerActivityAt, marker } from './issues.js';
+
+/** At most one heartbeat comment per this many minutes. */
+export const HEARTBEAT_EVERY_MIN = 5;
+
+/**
+ * -> { state: 'ok' | 'lost' | 'unknown', owner, heartbeat, error }
+ *   ok      - the task is mine (heartbeat: whether a renewal marker was posted);
+ *   lost    - another owner, or the task went back to the queue;
+ *   unknown - GitHub unavailable (no network, no gh); do not block work, only warn.
+ * view/post are replaced in tests.
+ */
+export function checkLease({ id, me, view = viewIssue, post = comment, now = Date.now(), heartbeat = true, everyMin = HEARTBEAT_EVERY_MIN }) {
+  let issue;
+  try {
+    issue = view(id);
+  } catch (e) {
+    return { state: 'unknown', owner: null, heartbeat: false, error: e?.recovery?.cause_hint || e?.message || String(e) };
+  }
+  if (!issue) return { state: 'unknown', owner: null, heartbeat: false, error: `issue #${id} not found` };
+  const owner = currentOwner(issue.comments ?? []);
+  if (!owner || owner.agent !== me) return { state: 'lost', owner: owner?.agent ?? null, heartbeat: false };
+  let beat = false;
+  const last = Date.parse(ownerActivityAt(issue.comments, owner) ?? '');
+  if (heartbeat && (!Number.isFinite(last) || now - last > everyMin * 60_000)) {
+    try {
+      post(id, marker('heartbeat', { agent: me, at: new Date(now).toISOString() }));
+      beat = true;
+    } catch {
+      /* renewal is best effort */
+    }
+  }
+  return { state: 'ok', owner: owner.agent, heartbeat: beat };
+}
+
+/** Shared "task was taken" response for commit / pr open. */
+export function leaseLostError(fail, id, lease, me) {
+  return fail('lease_lost', `#${id} is no longer your task${lease.owner ? ` - held by ${lease.owner}` : ' - it was returned to the queue'}`, {
+    cause_hint: `the lease expired (no activity for a long time) and the task went back to the queue; or CREW_AGENT (${me}) differs from the one used at claim`,
+    retry: `crew task claim ${id} - if the task is status:ready again; otherwise crew task next`,
+    stop_when: 'another agent took the task: do not push your branch, leave a note in the issue about what you finished',
+    next_actions: [`gh issue view ${id}`, `crew task claim ${id} (if ready)`, 'crew task next'],
+  });
+}