Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

48.3 KB
Raw Blame
/**
 * Perpetual Work Detectors
 *
 * Programmatic (no-LLM) "is there actionable work?" probes for perpetual
 * scheduled tasks (INTERVAL_TYPES.PERPETUAL in taskSchedule.js). A perpetual
 * task drains work back-to-back until its detector reports nothing actionable,
 * then PARKS on a recheck cadence (see taskSchedule.parkPerpetual). The detector
 * IS the "pre-run check": it must mirror the corresponding claim prompt's
 * skip-list so the drain converges to the SAME empty state the agent would
 * reach — otherwise the drain re-picks an issue the agent always skips and never
 * parks.
 *
 * The registry is pluggable: `detectActionableWork(taskType, app, opts)`
 * dispatches on the RESOLVED prompt task type (claim-issue, plan-task, …). A
 * task type with no registered detector returns `{ actionable: false,
 * reason: 'no-detector' }` so perpetual mode PARKS rather than drains blindly.
 *
 * Detector results carry a `transient` flag: a definitive "no work" (empty
 * actionable set) parks; a transient probe failure (gh unauthenticated, list
 * errored) is surfaced with `transient: true` so the caller skips THIS dispatch
 * without parking — the next evaluation tick retries instead of waiting out a
 * full recheck cadence on a blip.
 */

import { claimIssueNumber, collectGithubPrIssueNumbers, collectGitlabMrIssueNumbers, githubClaimPrArgs, githubPrRowsFromPages } from '../lib/issueClaimEvidence.js';
import { runCliBounded } from '../lib/runCliBounded.js';
import { readFile } from 'fs/promises';
import { join } from 'path';
import { emitLog } from './cosEvents.js';
import { parsePlanItems, extractAllIds, findInProgressIds, pickFirstAvailable } from '../lib/planIds.js';
import { readOriginRemoteUrl } from '../lib/gitRemote.js';
import { withGlabJson } from '../lib/glabArgs.js';
import { githubApiHost, hostFromOriginUrl } from '../lib/workTracker.js';
import { scrubSecretTokens } from '../lib/secretText.js';
import { redactPii } from '../lib/piiRedactionPatterns.js';
// The workflow markers live with the forge label vocabulary (name + color + the
// `label create` idiom the prompt bodies interpolate), so the detector and the
// live claim agent cannot drift on how "already decomposed" or "claimed and
// being worked" is spelled.
import { EPIC_DECOMPOSED_LABEL, EPIC_LABEL, IN_PROGRESS_LABEL } from '../lib/dispatchLabels.js';

export { EPIC_DECOMPOSED_LABEL };

// Labels that make a GitHub issue non-actionable for autonomous claiming. MUST
// stay in sync with the claim-issue prompt's Phase 1 skip-list
// (server/services/taskPromptDefaults/prompts.js). `needs-input` is the park
// label the agent applies when it decides an issue needs a human decision
// (claim-issue prompt Phase 3) — excluding it here is what lets a perpetual
// drain converge instead of re-picking the same ambiguous issue forever.
//
// This set is intentionally fixed/structural — a user's own reserved-for-humans
// labels (e.g. `good first issue`) are NOT added here. They're configured
// per-app via `taskMetadata.issueExcludeLabels` and unioned in at read time by
// `isActionableIssue`'s `excludeLabels` param, so the base skip-list stays the
// same across every install.
export const NON_ACTIONABLE_ISSUE_LABELS = new Set([
  IN_PROGRESS_LABEL, 'blocked', 'needs-input', 'future', 'wontfix', 'question', 'discussion'
]);

// Structural skip causes that are NOT label names. A configured exclude label
// colliding with one of these (`in-flight` especially — both UI consumers
// suppress that cause because counts.inFlight already carries it) would be
// indistinguishable from the structural skip, so the cause is prefixed on
// collision. Label-shaped structural names need no entry: the structural label
// check runs first and shadows a same-named configured label by design.
const STRUCTURAL_NON_LABEL_CAUSES = new Set(['assigned', 'in-flight', 'decomposed-epic', 'malformed']);

// Exported so the timeout path is directly testable with fake timers rather
// than a real 15s wait.
export const CLI_TIMEOUT_MS = 15000;

// How many actionable work items a detector carries back in `items`. The
// detectors exist for the perpetual drain (which only needs `actionable`/`count`),
// but the same scan is what the "/do:next — pick a specific item" picker needs, so
// each detector also returns the claimable items themselves. Capped so a repo with
// hundreds of open issues can't balloon the response the picker renders.
export const WORK_ITEM_LIMIT = 50;

// Cap on the CLI stderr detail carried into a transient reason — long enough to
// show the actual fault (an auth message, a rate-limit window, a DNS failure),
// short enough that a verbose CLI dump never bloats a log line or a toast.
const CLI_DETAIL_MAX_CHARS = 200;

/**
 * Redact a raw CLI stderr capture into a short, safe detail string for a
 * transient reason. Per AGENTS.md "Sensitive Data & Privacy", a forge CLI's
 * stderr can carry a hostname, tailnet name, or token, so it must be scrubbed
 * before it can reach a log line or a UI toast — `scrubSecretTokens` for
 * credential-shaped values, `redactPii` for hosts/paths/IPs/emails/etc. Keeps
 * only the LAST non-empty line: the actual failure is almost always the tail of
 * a gh/glab error, not its usage banner. Returns null for empty/blank stderr so
 * callers can tell "no detail available" apart from a detail that redacted to
 * an empty string.
 */
export function redactCliDetail(stderr) {
  const lines = String(stderr || '').split('\n').map((l) => l.trim()).filter(Boolean);
  if (lines.length === 0) return null;
  const detail = redactPii(scrubSecretTokens(lines[lines.length - 1]));
  return detail.length > CLI_DETAIL_MAX_CHARS ? `${detail.slice(0, CLI_DETAIL_MAX_CHARS)}…` : detail;
}

/** Best-effort CLI runner: never rejects or hangs; the detectors classify the result themselves. */
function runCli(cmd, args, cwd, env) {
  return runCliBounded(cmd, args, { cwd, env, timeoutMs: CLI_TIMEOUT_MS });
}

/**
 * Extract a GitHub issue number from a git ref ONLY when it matches a documented
 * claim pattern (`claim/issue-<num>`, `cos/<task>/issue-<num>/<agent>`, or the
 * slashdo `/do:next` branch `next/issue-<num>`, #8161).
 * Shares claimIssueNumber with the manual claim gate and PR evidence parser.
 */
export function issueNumberFromRef(ref) {
  return claimIssueNumber(ref);
}

/**
 * Resolve the FULL GitLab project namespace (every path segment before the final
 * repo segment) from the git origin remote — INCLUDING nested subgroups. The
 * shared `parseGitRemoteUrl` only accepts a two-segment `owner/repo`, so a
 * subgroup-nested project (`parent/subgroup/project`) resolves to null there and
 * never reaches the group probe below; parse the raw path here so nested subgroups
 * get the same owner-is-group short-circuit as a top-level group. GitLab subgroups
 * are the common layout, so this is the difference between the short-circuit
 * working and silently never firing for real GitLab projects. Returns null when
 * there's no origin remote or the URL has no namespace segment (a bare `repo`).
 * For a single-owner remote (`alice/repo`) this returns just `alice`, so the
 * user-namespace `--author` path keeps its old value.
 */
async function resolveGitlabNamespace(repoPath) {
  const url = await readOriginRemoteUrl(repoPath).catch(() => null);
  if (typeof url !== 'string' || !url.trim()) return null;
  const trimmed = url.trim().replace(/\.git$/i, '');
  // Extract the repo PATH (everything after the host) without mistaking any of the
  // host for it. A `[^/]+` host run stops at the path's first slash — and since a
  // host (bracketed IPv6 included) contains no slash, this isolates the path even
  // for `[2001:db8::1]/group/repo` and keeps a `:port` with the host. No numeric
  // segment is ever stripped from the path, so a numeric GitLab namespace
  // (`/1234/repo`) survives intact.
  let rawPath = null;
  const urlStyle = trimmed.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/(?:[^@/]+@)?[^/]+\/(.+)$/);
  if (urlStyle) {
    rawPath = urlStyle[1]; // scheme://[user@]host[:port]/PATH
  } else {
    // scp-style SSH: [user@]host:PATH — the host may be a bracketed IPv6 literal
    // (whose inner colons must NOT be read as the host/path separator).
    const scpStyle = trimmed.match(/^(?:[^@]+@)?(?:\[[^\]]+\]|[^:]+):(.+)$/);
    if (!scpStyle) return null;
    rawPath = scpStyle[1];
  }
  const segments = rawPath.replace(/^\/+/, '').split('/').filter(Boolean);
  if (segments.length < 2) return null; // need at least namespace + repo
  segments.pop(); // drop the repo segment; the rest is the (possibly nested) namespace
  return segments.join('/');
}

/**
 * Collect the set of issue numbers currently in flight, evidenced by an open
 * `claim/issue-<num>` / `cos/.../issue-<num>/...` / `next/issue-<num>` (slashdo
 * `/do:next`, #8161) branch (local or remote) or an open PR/MR source ref.
 * Local branches are supplementary; a failed PR/MR listing (timeout, auth,
 * rate limit) returns `{ error, detail }` rather than an under-counted set,
 * since a short set makes issues with an open PR look claimable. `forge` selects
 * how open changes are listed: GitHub PR head refs (`gh pr list`) vs GitLab
 * MR source branches (`glab mr list`).
 */
async function inFlightIssueNumbers(repoPath, forge = 'github', env) {
  const nums = new Set();
  // The branch list and the PR/MR list are independent CLI calls — run concurrently.
  const prListCall = forge === 'gitlab'
    ? runCli('glab', withGlabJson(['mr', 'list', '--per-page', '100']), repoPath, env)
    : runCli('gh', await withGithubHost(githubClaimPrArgs(), repoPath), repoPath, env);
  const [branchRes, prRes] = await Promise.all([
    runCli('git', ['branch', '-a', '--no-color', '--format=%(refname:short)'], repoPath, env),
    prListCall
  ]);
  if (prRes.code !== 0) {
    return { error: `${forge === 'gitlab' ? 'glab' : 'gh'}-unavailable`, detail: redactCliDetail(prRes.stderr) };
  }
  const refs = (branchRes.stdout || '').split('\n').map((s) => s.trim()).filter(Boolean);
  let changes;
  try { changes = JSON.parse(prRes.stdout); } catch { changes = null; }
  const changeNumbers = forge === 'gitlab'
    ? collectGitlabMrIssueNumbers(changes)
    : await collectGithubPrIssueNumbers(githubPrRowsFromPages(changes), async number => {
      const res = await runCli('gh', await withGithubHost([
        'api', '--paginate', '--slurp', `repos/{owner}/{repo}/pulls/${number}/commits?per_page=100`
      ], repoPath), repoPath, env);
      if (res.code !== 0) return null;
      try { return JSON.parse(res.stdout); } catch { return null; }
    });
  if (!changeNumbers) {
    return { error: `${forge === 'gitlab' ? 'glab' : 'gh'}-unavailable`, detail: 'Open change evidence is malformed or incomplete' };
  }
  for (const number of changeNumbers) nums.add(number);
  for (const ref of refs) {
    const n = issueNumberFromRef(ref);
    if (n != null) nums.add(n);
  }
  return { nums };
}

/**
 * Recognize a tracking/umbrella EPIC from its title alone — the programmatic
 * half of the claim-issue prompt's epic handling (`isActionableIssue` decides
 * what that means for claimability). Matches the epic-title conventions the
 * prompt names and the agent honors:
 *   - a trailing `(epic)` tag  — e.g. "Redesign nav (epic)"
 *   - a leading `[epic]` bracket or `Epic:` colon tag — e.g. "[Epic] Billing
 *     revamp", "[epic: theme] …", "Epic: Redesign nav" (case-insensitive)
 * The leading-tag branch is what makes an "[Epic] …" issue with no `epic` label
 * read as an epic at all (label check misses it, and it doesn't END in
 * "(epic)"). The `\b` + `[:\]]` terminator keeps a bare adjective ("Epic rework
 * of nav") and near-words ("[epicenter] …") from matching — only a real
 * bracketed/colon-delimited `epic` tag counts.
 */
export function titleMarksEpic(title) {
  const t = (title || '').trim().toLowerCase();
  return t.endsWith('(epic)') || /^\[?\s*epic\b\s*[:\]]/.test(t);
}

// True when an issue is a tracking/umbrella epic — by `epic` label or by the
// title conventions above. `labels` is the caller's already-lowercased list.
const isEpicIssue = (title, labels) => labels.includes(EPIC_LABEL) || titleMarksEpic(title);

/**
 * Decide whether a single forge issue (as returned by `gh`/`glab` issue list)
 * is autonomously claimable. Mirrors the claim-issue prompt's Phase 1 step 4
 * predicate: no in-flight claim/PR evidence, no assignee, no blocking label,
 * and — for an epic — not already decomposed. A scheduled dispatch is a fresh
 * run, so sharing a login never proves ownership of an earlier claim.
 *
 * An UNdecomposed epic counts as actionable: the claim agent's Phase 1b splits
 * it into per-slice issues (and then claims the first slice), which is real work
 * and the only way the queue moves when every remaining item is an epic. Once
 * that agent stamps `EPIC_DECOMPOSED_LABEL` on the parent, the epic drops out and
 * its children are ordinary claimable issues. A user who does not want a
 * particular epic auto-split puts a blocking label on it (`future`, `blocked`,
 * `needs-input`) — that works whether the epic is marked by label or only by its
 * title, which `epic` in `issueExcludeLabels` would not.
 *
 * `excludeLabels` is the app's configured `issueExcludeLabels`
 * (`taskMetadata.issueExcludeLabels`) — extra labels a user wants left for
 * human contributors (e.g. `good first issue`). It is UNIONED with
 * `NON_ACTIONABLE_ISSUE_LABELS`, never replacing it: the base set is
 * structural (in-progress/blocked/etc.), not user-configurable.
 */
export function isActionableIssue(issue, inFlight = new Set(), excludeLabels = null) {
  return issueSkipCause(issue, inFlight, excludeLabels) === null;
}

/**
 * Attribute WHY an issue is not claimable: the FIRST failing check from
 * `isActionableIssue`'s predicate order, as a short cause string. The cause
 * vocabulary is what the park breakdown (`skipCauses`) shows the user, so a
 * queue that parks on "0 of 88 open" reads as "49 needs-input, 17 blocked, 13
 * decomposed-epic" — the difference between "the task is broken" and "the work
 * is waiting on you". Returns null for a claimable issue (the same contract
 * `isActionableIssue` keys on), the structural label's own name for a
 * label-skip (e.g. `needs-input`, `blocked`), the configured exclude label's
 * name for a user-reserved skip, and `assigned` / `in-flight` /
 * `decomposed-epic` / `malformed` for the structural checks. Not exported: the
 * detector tests exercise it behaviorally through `skipCauses`, and the
 * dead-exports guard keeps it honest about that.
 */
function issueSkipCause(issue, inFlight = new Set(), excludeLabels = null) {
  if (!issue || typeof issue.number !== 'number') return 'malformed';
  if (inFlight.has(issue.number)) return 'in-flight';
  const assignees = Array.isArray(issue.assignees) ? issue.assignees : [];
  if (assignees.length > 0) return 'assigned';
  const labels = (Array.isArray(issue.labels) ? issue.labels : [])
    .map((l) => (typeof l === 'string' ? l : l?.name) || '')
    .map((s) => s.toLowerCase());
  const structural = labels.find((l) => NON_ACTIONABLE_ISSUE_LABELS.has(l));
  if (structural) return structural;
  if (excludeLabels) {
    const excluded = labels.find((l) => excludeLabels.has(l));
    // Prefix only on collision with a non-label structural cause so the two
    // remain distinguishable in the park breakdown; every other configured
    // label keeps its bare name.
    if (excluded) return STRUCTURAL_NON_LABEL_CAUSES.has(excluded) ? `excluded-label:${excluded}` : excluded;
  }
  // Marker first: the label scan is a 2–5 element array walk, while isEpicIssue
  // lowercases and regex-tests the title. Only a decomposed issue needs the
  // epic check, so this skips that work for essentially every issue in a
  // 500-issue fetch.
  if (labels.includes(EPIC_DECOMPOSED_LABEL) && isEpicIssue(issue.title, labels)) return 'decomposed-epic';
  return null;
}

/**
 * Resolve the authenticated account's login on `cli`. Shared by GitLab's
 * `--author`-token lookup and BOTH forges' trusted-set seed, so the probe and
 * its `<cli>-unavailable` sentinel exist once.
 */
async function resolveGithubHost(repoPath) {
  const origin = await readOriginRemoteUrl(repoPath).catch(() => null);
  // GitHub's public host remains the safe default for a checkout without a
  // readable origin; managed GitHub apps normally provide one, and a parsed
  // enterprise origin is always preferred so the identity probe cannot drift
  // to github.com.
  return githubApiHost(hostFromOriginUrl(origin)) || 'github.com';
}

const withGithubHost = async (args, repoPath) => [
  args[0],
  '--hostname',
  await resolveGithubHost(repoPath),
  ...args.slice(1)
];

async function resolveAuthenticatedLogin(cli, args, repoPath, env) {
  const probeArgs = cli === 'gh' ? await withGithubHost(args, repoPath) : args;
  const res = await runCli(cli, probeArgs, repoPath, env);
  const rawLogin = cli === 'glab'
    ? (await import('../lib/streamJsonParser.js')).safeParse(res.stdout)?.username
    : res.stdout;
  const login = typeof rawLogin === 'string' ? rawLogin.trim() : '';
  return (res.code !== 0 || !login) ? { error: `${cli}-unavailable`, detail: redactCliDetail(res.stderr) } : { login };
}

/**
 * Collect the lowercased login of the authenticated account plus every account
 * the forge reports as having repo/project access — the trusted author set for
 * the `collaborators` gate. Returns `{ error }` on ANY probe failure rather than
 * a partial set: degrading to just `self` would silently NARROW the gate (work
 * hides with no explanation), and degrading to "everyone" would silently WIDEN a
 * security boundary. Both are worse than retrying next tick, so the failure
 * carries a `remedy` the caller can surface instead.
 */
async function resolveTrustedLogins(cfg, repoPath, env) {
  const { login, error, detail } = await resolveAuthenticatedLogin(cfg.cli, cfg.selfLoginArgs, repoPath, env);
  if (error) return { error, detail };
  const membersArgs = cfg.cli === 'gh'
    ? await withGithubHost(cfg.membersArgs, repoPath)
    : cfg.membersArgs;
  const res = await runCli(cfg.cli, membersArgs, repoPath, env);
  if (res.code !== 0) return { error: cfg.membersFail, remedy: cfg.membersRemedy, detail: redactCliDetail(res.stderr) };
  const lines = (res.stdout || '').split('\n').filter(line => line.trim());
  // glab api emits raw NDJSON; unlike gh api it has no -q selector.
  const parseMember = cfg.cli === 'glab' ? (await import('../lib/streamJsonParser.js')).safeParse : null;
  const members = parseMember ? lines.map(line => parseMember(line)?.username) : lines;
  if (members.some(member => typeof member !== 'string' || !member.trim())) {
    return { error: cfg.membersFail, remedy: cfg.membersRemedy };
  }
  const logins = new Set([login.toLowerCase()]);
  for (const line of members) {
    const member = line.trim().toLowerCase();
    if (member) logins.add(member);
  }
  return { logins };
}

// Map raw forge issues to the forge-agnostic shape both the skip-list
// (`isActionableIssue`) and the `collaborators` author gate read. Only the two
// source keys differ — GitLab keys the number on `iid` and the author login on
// `username` — so the mapping itself lives once, and every downstream filter
// sees ONE record shape.
const normalizeIssues = (raw, numberKey, authorKey) => raw.map((r) => ({
  number: r[numberKey],
  title: r.title,
  labels: r.labels,
  assignees: r.assignees,
  authorLogin: (r.author?.[authorKey] || '').toLowerCase()
}));

// A forge can return the same candidate set in a different order, especially
// after the collaborators author fan-out. Keep picker order untouched, but use
// a canonical representation for the perpetual drain's set comparison.
const canonicalizeIds = (ids) => [...new Set(ids
  .filter((id) => id != null)
  .map((id) => String(id)))].sort((a, b) => {
  const numericA = Number(a);
  const numericB = Number(b);
  return Number.isFinite(numericA) && Number.isFinite(numericB)
    ? numericA - numericB
    : a.localeCompare(b);
});

const GLAB_SELF_LOGIN_ARGS = ['api', 'user'];

// Upper bound on the `--author <login>` queries the `collaborators` gate fans
// out per detection pass. Each login costs one CLI round-trip, and this runs on
// the perpetual-work cadence, so a repo with a large org-wide collaborator list
// must not turn one detection into hundreds of `gh` shells. When the trusted set
// exceeds the cap, the first N (you first, then the member listing order) are
// queried and the truncation is LOGGED — never dropped silently.
const MAX_COLLABORATOR_AUTHOR_QUERIES = 25;

/**
 * Env for PortOS-owned `gh` probes against a managed app.
 *
 * Agents already get `resolveForgeTokenEnv` so `gh` authenticates as the app's
 * pinned (or owner-matched) account. The claim-issue detector used to inherit
 * the install's ambient `GH_TOKEN` / active `gh` user instead, so a private
 * repo under a different logged-in account failed the list as a "transient
 * forge" blip and never dispatched. A caller-supplied `env` wins (prompt
 * preloads already resolve the same overlay); otherwise mint and merge here.
 * `GITHUB_TOKEN` / enterprise aliases from another account are dropped so they
 * cannot outrank the pin.
 */
async function resolveGithubDetectorEnv(repoPath, env) {
  if (env) return env;
  const { resolveForgeTokenEnv } = await import('./forgeAuth.js');
  const overlay = await resolveForgeTokenEnv(repoPath);
  if (!overlay?.GH_TOKEN && !overlay?.GH_ENTERPRISE_TOKEN) return undefined;
  const merged = { ...process.env };
  for (const key of ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN']) delete merged[key];
  return { ...merged, ...overlay };
}

// Per-forge config for the shared issue detector. Each entry captures only what
// differs between GitHub (`gh`) and GitLab (`glab`): the CLI + issue-list args,
// how owner/self/collaborators mode resolves the author filter, the transient
// reason strings, and how a raw issue maps to the forge-agnostic
// `{ number, title, labels, assignees, authorLogin }` shape. The control flow
// itself lives once in `detectForgeIssues`. `inFlightForge` selects the
// in-flight scan dialect.
const FORGE_ISSUE_CONFIG = {
  'claim-issue': {
    cli: 'gh',
    inFlightForge: 'github',
    // `author` is requested unconditionally: it costs nothing on the paths that
    // ignore it, and the `collaborators` gate can only be applied to the listing
    // (gh's `--author` takes exactly one account, so a trusted SET can't be
    // pushed into the query).
    // `--limit 500` (gh paginates internally up to this count in one call, per
    // its own `--limit` docs) rather than 100: the label filter below (fixed
    // NON_ACTIONABLE_ISSUE_LABELS plus any configured `issueExcludeLabels`)
    // runs client-side AFTER this fetch, so a small fetch cap risks the
    // detector parking on a false "no actionable issues" when the first page
    // happens to be full of excluded/in-flight/decomposed-epic issues even
    // though real work exists further down the queue. Matches the same
    // tradeoff the /do:next auto-pick walk already makes for the same reason.
    listArgs: ['issue', 'list', '--state', 'open', '--search', 'sort:created-asc', '--json', 'number,assignees,labels,title,author', '--limit', '500'],
    listFail: 'gh-list-failed',
    parseFail: 'gh-parse-failed',
    // Park reason when the owner filter resolves to a non-authoring owner. On
    // GitHub that owner is an ORG; the toast copy is org-flavored to match.
    ownerIsOrgReason: 'owner-is-org',
    // Authoritative repo owner (org or user) + whether that owner is an org, via
    // gh; transient if gh is unauthenticated / not a GitHub remote. `isOrg` lets
    // detectForgeIssues short-circuit the owner-filter org trap — an org login is
    // never an issue author, so `--author <org>` is guaranteed to match nothing.
    resolveOwner: async (repoPath, env) => {
      const r = await runCli('gh', ['repo', 'view', '--json', 'owner,isInOrganization'], repoPath, env);
      if (r.code !== 0) return { error: 'gh-unavailable', detail: redactCliDetail(r.stderr) };
      let parsed;
      try {
        parsed = JSON.parse(r.stdout || '{}');
      } catch {
        return { error: 'gh-unavailable' };
      }
      const owner = (parsed?.owner?.login || '').trim();
      if (!owner) return { error: 'gh-unavailable' };
      return { owner, isOrg: parsed?.isInOrganization === true };
    },
    // `--self` mode: gh natively understands the `@me` token for `--author`, so
    // no author-filter lookup is needed — the API resolves it to the authenticated
    // user. `selfLoginArgs` resolves that account for collaborator mode.
    resolveSelf: async () => ({ author: '@me' }),
    // `collaborators` mode: you + everyone with repo access. `{owner}`/`{repo}`
    // are gh's own placeholders, resolved from the checked-out remote. A 403 here
    // (no push access ⇒ the collaborators endpoint is forbidden) is reported with
    // its remedy, not papered over — see resolveTrustedLogins.
    selfLoginArgs: ['api', 'user', '-q', '.login'],
    membersArgs: ['api', '--paginate', 'repos/{owner}/{repo}/collaborators', '-q', '.[].login'],
    membersFail: 'gh-collaborators-failed',
    membersRemedy: 'the "Me + collaborators" filter needs a gh account with push access to this repo — pick a different author filter, or re-auth gh',
    normalize: (raw) => normalizeIssues(raw, 'number', 'login')
  },
  'claim-issue-gitlab': {
    cli: 'glab',
    inFlightForge: 'gitlab',
    // `--per-page` maxes out at 100 (GitLab's own per-call ceiling; unlike
    // gh's `--limit`, there's no single-call "give me more" here) — same
    // residual gap the /do:next auto-pick walk documents for GitLab: a busy
    // tracker whose first page is dominated by excluded/in-flight/
    // decomposed-epic issues can still park on a false "no actionable issues"
    // despite real work further down the queue. `--issues-label`-style curation is the
    // practical mitigation there; this detector has no equivalent knob yet.
    listArgs: withGlabJson(['issue', 'list', '--per-page', '100']),
    listFail: 'glab-list-failed',
    parseFail: 'glab-parse-failed',
    // Park reason when the owner filter resolves to a non-authoring owner. On
    // GitLab that owner is a GROUP, not an "org"; the toast copy is group-flavored
    // to match (a GitLab user would never call their namespace an org).
    ownerIsOrgReason: 'owner-is-group',
    // GitLab has no authoritative `gh repo view` equivalent here; resolve the
    // author filter from the project namespace (git remote owner), matching the
    // claim-issue-gitlab prompt. GitLab can't tell a user namespace from a GROUP
    // (or nested subgroup) from the remote URL alone, so probe:
    // `glab api groups/<url-encoded-namespace>` returns 200 for a group/subgroup
    // and 404 for a user namespace. A group is never an issue author, so populate
    // `isOrg: true` for groups and let detectForgeIssues fire the same owner-filter
    // short-circuit GitHub uses — no new branch logic. The namespace is URL-encoded
    // so a nested subgroup path (`parent/subgroup`) hits the group endpoint as
    // `groups/parent%2Fsubgroup`. A probe failure (network/unauth/non-200) degrades
    // to isOrg:false → the pre-existing `--author <owner>` behavior, so no new
    // transient park appears.
    //
    // Numeric-namespace guard: `groups/:id` treats an ALL-NUMERIC `:id` as a
    // database group ID, not a path — so probing `groups/1234` could match an
    // unrelated group by ID and falsely park a user's `/1234/widget` as
    // owner-is-group. GitLab forbids all-numeric namespace *paths* precisely to
    // avoid this id/path ambiguity, so such a namespace shouldn't occur; if one
    // somehow does, skip the ambiguous probe and take the safe `--author <ns>`
    // path (isOrg:false). Nested subgroups are URL-encoded (`parent%2Fsub`) and so
    // are never all-numeric — they still probe normally.
    resolveOwner: async (repoPath, env) => {
      const namespace = await resolveGitlabNamespace(repoPath);
      if (!namespace) return { error: 'glab-owner-unresolved' };
      const probe = /^\d+$/.test(namespace)
        ? { code: 1 }
        : await runCli('glab', ['api', `groups/${encodeURIComponent(namespace)}`], repoPath, env);
      return { owner: namespace, isOrg: probe.code === 0 };
    },
    // `--self` mode: glab's `--author` expects a username (no `@me` token), so
    // resolve the authenticated account via the API; the same lookup also powers
    // the self-assignee retry check. It is transient if glab is unauthenticated
    // or unreachable.
    resolveSelf: async (repoPath, env) => {
      const { login, error, detail } = await resolveAuthenticatedLogin('glab', GLAB_SELF_LOGIN_ARGS, repoPath, env);
      return error ? { error, detail } : { author: login };
    },
    // `collaborators` mode: you + every project member. `members/all` (not
    // `members`) so members INHERITED from the parent group/subgroup count —
    // group-level access is how most GitLab teams are actually granted. `:id` is
    // glab's own project placeholder, resolved from the checked-out remote.
    selfLoginArgs: GLAB_SELF_LOGIN_ARGS,
    membersArgs: ['api', '--paginate', 'projects/:id/members/all', '--output', 'ndjson'],
    membersFail: 'glab-members-failed',
    membersRemedy: 'the "Me + collaborators" filter needs a glab account that can read this project\'s member list — pick a different author filter, or re-auth glab',
    // GitLab keys the number on `iid`, the author login on `username`, and
    // returns labels as plain strings.
    normalize: (raw) => normalizeIssues(raw, 'iid', 'username')
  }
};

/**
 * Best-effort count of ALL open issues in a repo, ignoring the author filter.
 * Used to disambiguate an empty *author-filtered* list: a repo whose only open
 * issues were filed by someone else must not be reported as "no open issues".
 * Any probe failure (list error / bad JSON / non-array) returns 0 so the caller
 * falls back to the definitive `no-open-issues` result rather than inventing a
 * phantom count. Reuses `cfg.listArgs`, which is the base list WITHOUT the
 * `--author` filter (the filter is appended separately in detectForgeIssues).
 */
async function countOpenIssuesUnfiltered(cfg, repoPath, env) {
  const res = await runCli(cfg.cli, [...cfg.listArgs], repoPath, env);
  if (res.code !== 0) return 0;
  let raw;
  try {
    raw = JSON.parse(res.stdout || '[]');
  } catch {
    return 0;
  }
  return Array.isArray(raw) ? raw.length : 0;
}

/**
 * Shape for a transient (non-parking) probe failure. Carries the CLI that
 * failed so the caller can attribute the fault to `gh` vs `glab` instead of
 * guessing from the task-type name — a `claim-work` request only resolves to
 * its forge-specific type internally, so the name is not a reliable signal.
 * `remedy` rides along when the probe named a fault that won't self-clear (a
 * permission the token doesn't have), so the on-demand toast can print the way
 * out instead of "try again shortly".
 */
const forgeTransient = (cfg, reason, remedy = null, detail = null) => ({
  actionable: false, count: 0, cli: cfg.cli, reason, remedy, detail, transient: true
});

/**
 * List a repo's open issues that pass the author-trust gate — the one place the
 * author filter is resolved, for both the claim detector and the prompt-context
 * listing. Honors the author filter ('self' = only issues YOU filed (`@me`), the
 * default and the slashdo `/do:next --self` security boundary; 'collaborators' =
 * you plus everyone with repo/project access; 'owner' = only the repo owner's
 * issues; 'any' = every author). Neither caller can skip the `collaborators`
 * post-filter because it lives here.
 *
 * Returns one of:
 *  - `{ transient }` — a probe failure (the forge-flavored transient result);
 *    skip this dispatch and retry next tick rather than parking a full cadence.
 *  - `{ parkedOrgOwner: true, resolvedEnv }` — the `owner` filter resolved to a
 *    non-authoring owner (a GitHub ORG / GitLab GROUP), so no issue can match.
 *  - `{ issues, truncated, authorApplied, resolvedEnv }` — the trusted listing.
 * `resolvedEnv` is the env the CLI calls ran under, so a caller's follow-up
 * probes authenticate as the same account.
 */
async function fetchTrustedForgeIssues(cfg, repoPath, { issueAuthorFilter = 'self' } = {}, env) {
  const resolvedEnv = cfg.cli === 'gh' ? await resolveGithubDetectorEnv(repoPath, env) : env;
  const transient = (reason, remedy, detail) => ({ transient: forgeTransient(cfg, reason, remedy, detail) });

  const args = [...cfg.listArgs];
  // Resolve the author filter symmetrically with resolveIssueAuthorFilterBlock:
  // 'any' = no filter; 'collaborators' = you + everyone with repo/project access
  // (applied to the listing, since neither CLI's `--author` accepts a SET);
  // 'owner' = repo/project owner; everything else (the 'self' default plus any
  // out-of-vocab value) = the @me security boundary.
  let authorApplied = false;
  // Trusted login set for `collaborators` mode (null on every other path).
  // Neither CLI's `--author` accepts a SET, so the gate fans out into ONE
  // `--author <login>` query per trusted login and merges (see below) — the same
  // server-side-filtered shape `self`/`owner` use, so `--limit 100` bounds
  // *authored* issues rather than paging the 100 oldest issues by any author.
  // `authorApplied` is still set, so an empty merged list gets the same
  // `no-authored-issues` treatment that tells the user to widen the filter.
  let trustedLogins = null;
  if (issueAuthorFilter === 'any') {
    // no --author filter
  } else if (issueAuthorFilter === 'collaborators') {
    const { logins, error, remedy, detail } = await resolveTrustedLogins(cfg, repoPath, resolvedEnv);
    if (error) return transient(error, remedy, detail);
    trustedLogins = logins;
    authorApplied = true;
  } else if (issueAuthorFilter === 'owner') {
    const { owner, isOrg, error, detail } = await cfg.resolveOwner(repoPath, resolvedEnv);
    if (error) return transient(error, null, detail);
    // The owner filter resolved to a non-authoring owner (a GitHub ORG or a
    // GitLab GROUP), which can never be an issue author — `--author <owner>` is
    // guaranteed to match zero. Skip that empty query; the caller reports the
    // forge-flavored short-circuit reason (`owner-is-org` / `owner-is-group`), so
    // the toast steers the user to 'self'/'any' instead of implying a
    // personal-username mismatch (the failure that motivated this).
    if (isOrg) return { parkedOrgOwner: true, resolvedEnv };
    args.push('--author', owner);
    authorApplied = true;
  } else {
    const { author, error, detail } = await cfg.resolveSelf(repoPath, resolvedEnv);
    if (error) return transient(error, null, detail);
    args.push('--author', author);
    authorApplied = true;
  }

  // One issue-list invocation: run it, parse it, and report the forge-flavored
  // transient reason on any failure. Shared by the single-query paths and by the
  // `collaborators` per-login fan-out below.
  let listingTruncated = false;
  const listIssues = async (extraArgs = []) => {
    const res = await runCli(cfg.cli, [...args, ...extraArgs], repoPath, resolvedEnv);
    if (res.code !== 0) return { error: cfg.listFail, detail: redactCliDetail(res.stderr) };
    let parsed;
    try {
      parsed = JSON.parse(res.stdout || '[]');
    } catch {
      return { error: cfg.parseFail };
    }
    if (!Array.isArray(parsed)) return { error: cfg.parseFail };
    if (parsed.length >= (cfg.cli === 'gh' ? 500 : 100)) listingTruncated = true;
    return { issues: cfg.normalize(parsed) };
  };

  let issues;
  if (trustedLogins) {
    // Fan out one server-side `--author` query per trusted login and merge by
    // issue number. Post-filtering a single unfiltered page would silently hide
    // a claimable collaborator-filed issue on any repo with more than
    // `--limit 100` open issues (it would park with `no-authored-issues` while
    // the same repo works fine under `self`).
    const logins = [...trustedLogins];
    const queried = logins.slice(0, MAX_COLLABORATOR_AUTHOR_QUERIES);
    if (queried.length < logins.length) {
      // Never silent: a truncated set means issues from the dropped logins are
      // invisible this pass, which is exactly the failure mode being fixed.
      console.warn(`⚠️ Collaborators author filter capped at ${queried.length} of ${logins.length} trusted logins — issues filed by the other ${logins.length - queried.length} are not listed this pass`);
    }
    const merged = new Map();
    for (const login of queried) {
      const out = await listIssues(['--author', login]);
      if (out.error) return transient(out.error, null, out.detail);
      for (const issue of out.issues) merged.set(issue.number, issue);
    }
    issues = [...merged.values()];
  } else {
    const out = await listIssues();
    if (out.error) return transient(out.error, null, out.detail);
    issues = out.issues;
  }

  // `collaborators` gate, belt-and-braces over the `--author` queries above:
  // keep only issues whose author is in the trusted set. An unresolvable author
  // (missing/blank login) is DROPPED, never kept — the gate is a security
  // boundary, so "can't tell who filed it" resolves to "not trusted".
  if (trustedLogins) issues = issues.filter((i) => trustedLogins.has(i.authorLogin));

  return {
    issues,
    truncated: listingTruncated || (trustedLogins?.size || 0) > MAX_COLLABORATOR_AUTHOR_QUERIES,
    authorApplied,
    resolvedEnv
  };
}

/**
 * Shared claim-issue detector for both forges (config in FORGE_ISSUE_CONFIG).
 * Counts open issues that pass the same skip-list the claim agent applies, over
 * the author-trusted listing from `fetchTrustedForgeIssues`. The in-flight scan
 * runs only when the list is non-empty, so an empty queue parks without a
 * wasted branch/PR scan.
 */
async function detectForgeIssues(forgeKey, app, { issueAuthorFilter = 'self', issueExcludeLabels = [], requireComplete = false } = {}, env) {
  const cfg = FORGE_ISSUE_CONFIG[forgeKey];
  const repoPath = app?.repoPath;
  if (!repoPath) return { actionable: false, count: 0, reason: 'no-repo-path' };

  // Shared shape for a "parked" (no actionable work) result where only `reason`
  // and `total` (the open-issue denominator) vary. `count`/`inFlightCount`/
  // `filteredCount` are always 0 on these paths — the issues are excluded
  // upstream (author filter / empty repo), never by the skip-list — so the toast
  // reads a clean "0 of N open" with no redundant "N filtered".
  const parked = (reason, total = 0) => ({
    actionable: false, count: 0, total, inFlightCount: 0, filteredCount: 0, items: [], reason
  });

  const listing = await fetchTrustedForgeIssues(cfg, repoPath, { issueAuthorFilter }, env);
  if (listing.transient) return listing.transient;
  const { resolvedEnv } = listing;
  if (listing.parkedOrgOwner) {
    return parked(cfg.ownerIsOrgReason, await countOpenIssuesUnfiltered(cfg, repoPath, resolvedEnv));
  }
  const { issues, truncated, authorApplied } = listing;

  if (requireComplete && truncated) return forgeTransient(cfg, 'incomplete-issue-page');

  if (issues.length === 0) {
    // An empty *filtered* list is ambiguous: the repo may truly have no open
    // issues, OR it has open issues that just don't match the author filter —
    // e.g. `self`/@me resolving to a different identity than whoever filed the
    // issues, a non-org `owner` who simply filed none, or a queue of
    // outsider-filed issues under the `collaborators` gate. (The org/group-owner
    // trap is caught earlier with the distinct `owner-is-org`/`owner-is-group`
    // reason.)
    // Reporting a flat "no open issues" there hid a claimable queue behind a
    // full recheck park (the "open issues exist but the task still parked"
    // failure this fixes). Recover the unfiltered count with a re-probe WITHOUT
    // the author filter — and if issues
    // exist, park with the actionable `no-authored-issues` reason + the real open
    // count so the user is told to widen the filter, not that there is nothing
    // to do. The count is raw open issues (any author), not claimable ones —
    // best effort: switching to `any` may still yield `no-actionable-issues`
    // when the other-authored issues are all blocked/assigned/decomposed
    // epics. Counting claimable ones would cost the full skip-list scan here.
    if (authorApplied) {
      const openCount = await countOpenIssuesUnfiltered(cfg, repoPath, resolvedEnv);
      if (openCount > 0) return parked('no-authored-issues', openCount);
    }
    return parked('no-open-issues');
  }

  const inFlightResult = await inFlightIssueNumbers(repoPath, cfg.inFlightForge, resolvedEnv);
  if (inFlightResult.error) {
    console.log(`⏭️ In-flight claim evidence unavailable (${inFlightResult.error}); skipping this dispatch`);
    return forgeTransient(cfg, inFlightResult.error, null, inFlightResult.detail);
  }
  const inFlight = inFlightResult.nums;
  const total = issues.length;
  // How many of the OPEN issues were skipped only because a claim/PR is already
  // in flight for them (stale post-merge branches count here). Surfacing this
  // separately from the label/assignee/decomposed-epic filter tells the user
  // WHY an apparently-non-empty queue yields zero claimable work — the exact confusion
  // behind "40 open issues but it parked."
  const inFlightCount = issues.filter((i) => typeof i.number === 'number' && inFlight.has(i.number)).length;
  const excludeSet = Array.isArray(issueExcludeLabels) && issueExcludeLabels.length > 0
    ? new Set(issueExcludeLabels.map((l) => String(l).toLowerCase()))
    : null;
  const actionable = issues.filter((issue) => isActionableIssue(issue, inFlight, excludeSet));
  const filteredCount = Math.max(0, total - actionable.length - inFlightCount);
  // Per-cause attribution of every skip, so a park on a non-empty queue can say
  // WHY each issue was filtered ("49 needs-input, 17 blocked, …") instead of a
  // bare "78 filtered". `inFlightCount` already accounts for the in-flight
  // skips separately, so `in-flight` here is informational only — the counts
  // sum to `total` only when the queue holds no malformed records.
  // Null-prototype: a configured exclude label named `constructor` (or any
  // other Object.prototype key) must count as a cause, not inherit the
  // inherited property and corrupt the counter.
  const skipCauses = Object.create(null);
  if (actionable.length === 0 && total > 0) {
    for (const issue of issues) {
      const cause = issueSkipCause(issue, inFlight, excludeSet);
      if (cause != null) skipCauses[cause] = (skipCauses[cause] || 0) + 1;
    }
  }
  return {
    actionable: actionable.length > 0,
    count: actionable.length,
    total,
    inFlightCount,
    filteredCount,
    skipCauses,
    reason: actionable.length > 0 ? 'actionable-issues' : 'no-actionable-issues',
    sample: actionable.slice(0, 5).map((i) => i.number),
    // The perpetual drain uses the complete candidate set to detect a
    // successful agent that exited without claiming anything. `sample` is
    // intentionally capped for UI payloads, so it cannot serve as that brake.
    signature: JSON.stringify(canonicalizeIds(actionable.map((i) => i.number))),
    items: actionable.slice(0, WORK_ITEM_LIMIT).map((i) => ({ ref: String(i.number), title: i.title || '' }))
  };
}

/**
 * List prompt inputs using the same author-resolution boundary as claiming.
 * Prompt context observes author and configured label policy without hiding
 * blocked/assigned work that a non-claim task may need to inspect. Claim
 * preloads opt into the same structural label exclusions as the detector.
 */
export async function listConfiguredForgeIssues(cli, app, { issueAuthorFilter = 'self', issueExcludeLabels = [], excludeNonActionableLabels = false } = {}, env) {
  const cfg = FORGE_ISSUE_CONFIG[cli === 'glab' ? 'claim-issue-gitlab' : 'claim-issue'];
  const repoPath = app?.repoPath;
  if (!repoPath) return { ok: false, issues: [], truncated: false, error: 'no-repo-path' };

  const listing = await fetchTrustedForgeIssues(cfg, repoPath, { issueAuthorFilter }, env);
  if (listing.transient) {
    return { ok: false, issues: [], truncated: false, error: listing.transient.detail || listing.transient.reason || '' };
  }
  if (listing.parkedOrgOwner) return { ok: true, issues: [], truncated: false };

  const excluded = new Set((Array.isArray(issueExcludeLabels) ? issueExcludeLabels : []).map((label) => String(label).trim().toLowerCase()));
  if (excludeNonActionableLabels) {
    for (const label of NON_ACTIONABLE_ISSUE_LABELS) excluded.add(label);
  }
  return {
    ok: true,
    truncated: listing.truncated,
    issues: listing.issues.filter((issue) => !(issue.labels || []).some((label) =>
      excluded.has(String(typeof label === 'string' ? label : label?.name).trim().toLowerCase())
    ))
  };
}

// Forge-specific detector entry points (thin wrappers over the shared factory).
export const detectGithubIssues = (app, opts) => detectForgeIssues('claim-issue', app, opts);
export const detectGitlabIssues = (app, opts) => detectForgeIssues('claim-issue-gitlab', app, opts);

/**
 * Human-readable title for a PLAN.md item — the checkbox line's text with the
 * trailing HTML comments (`<!-- NEEDS_INPUT -->`, drift markers) and surrounding
 * whitespace stripped, so the picker shows the item, not the bookkeeping.
 */
function planItemTitle(item) {
  return (item.rest || '').replace(/<!--[\s\S]*?-->/g, '').trim();
}

/**
 * plan-task detector. Mirrors applyPlanIdMetadata's pick gate: an item is
 * actionable when it is unchecked, not blocked on human input (NEEDS_INPUT),
 * not drift-flagged, carries an id, and isn't already in flight via a
 * `claim/<slug>` branch/PR.
 */
export async function detectPlanTask(app) {
  const repoPath = app?.repoPath;
  if (!repoPath) return { actionable: false, count: 0, reason: 'no-repo-path' };
  const planMd = await readFile(join(repoPath, 'PLAN.md'), 'utf-8').catch(() => '');
  if (!planMd) return { actionable: false, count: 0, reason: 'no-plan' };

  const items = parsePlanItems(planMd);
  const knownIds = new Set(extractAllIds(planMd));
  const inFlight = await findInProgressIds(repoPath, knownIds).catch(() => new Set());
  const pick = pickFirstAvailable(items, inFlight);
  const available = items.filter((it) =>
    !it.checked && !it.needsInput && !it.drifted && it.id && !inFlight.has(it.id)
  );
  return {
    actionable: !!pick,
    count: available.length,
    reason: pick ? 'actionable-plan-items' : 'no-actionable-plan-items',
    // Keep the signature complete even though the picker payload is capped.
    // PLAN.md order is meaningful because pickFirstAvailable chooses the first
    // eligible item; unlike forge issue sets, preserve that order in the brake.
    signature: JSON.stringify(available.map((it) => it.id)),
    items: available.slice(0, WORK_ITEM_LIMIT).map((it) => ({ ref: it.id, title: planItemTitle(it) }))
  };
}

// ============================================================
// Registry
// ============================================================

const DETECTORS = new Map();

export function registerWorkDetector(taskType, fn) {
  DETECTORS.set(taskType, fn);
}

export function getWorkDetector(taskType) {
  return DETECTORS.get(taskType) || null;
}

export function hasWorkDetector(taskType) {
  return DETECTORS.has(taskType);
}

// Built-in detectors. claim-work resolves to one of these RESOLVED prompt task
// types before dispatch, so claim-work itself needs no detector. The JIRA claim
// flow (claim-issue-jira) has no detector yet — perpetual mode on a JIRA-tracked
// app parks with reason 'no-detector' until one is registered.
registerWorkDetector('claim-issue', detectGithubIssues);
registerWorkDetector('claim-issue-gitlab', detectGitlabIssues);
registerWorkDetector('plan-task', detectPlanTask);

/**
 * Probe whether `taskType` has actionable work for `app`. Always resolves to a
 * normalized shape: `{ actionable, count, reason, transient?, hasDetector }`.
 * A detector throw is caught and reported as a transient failure so the caller
 * skips (and retries) rather than parking on a broken probe.
 */
export async function detectActionableWork(taskType, app, opts = {}) {
  const detector = DETECTORS.get(taskType);
  if (!detector) {
    return { actionable: false, count: 0, reason: 'no-detector', hasDetector: false };
  }
  const result = await detector(app, opts).catch((err) => {
    emitLog('warn', `Perpetual work-detector for ${taskType} errored: ${err.message}`, { taskType, appId: app?.id }, '🔁 Perpetual');
    return { actionable: false, count: 0, reason: `detector-error: ${err.message}`, transient: true };
  });
  // Every detector (and the catch above) returns `count`, so spread last.
  return { ...result, hasDetector: true };
}