@clipboard-health/groundcrew 4.34.2 → 4.35.0

package/README.md

@@ -94,6 +94,7 @@ crew source list|verify [<source>]                       # inspect configured ta
 crew task list [--source <name>]                         # list tasks across sources
 crew task get <TASK> [--source <name>] [--prompt]        # inspect one task or its prompt
 crew task create "Title" --source <name> [--agent <name>] # create a source task
+crew task done <TASK> [--allow-dirty]                    # mark a no-PR task done
 crew task validate [<source>]                            # validate task content
 crew status [<TASK>]                                   # inspect current state or one task
 crew run [--watch]                                       # one-shot or --watch forever

package/dist/cli.js

@@ -136,8 +136,8 @@ const SUBCOMMANDS = {
         invoke: sourceCli,
     },
     task: {
-        summary: "List, get, and create tasks across configured sources",
-        usage: "<list|get|create> [...]",
+        summary: "List, get, create, and complete tasks across configured sources",
+        usage: "<list|get|create|done|validate> [...]",
         invoke: taskCli,
     },
     status: {

package/dist/commands/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/commands/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EACL,KAAK,UAAU,EAGf,KAAK,KAAK,EAEX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,CAAC,UAAU,EAAE;QACpB,KAAK,EAAE,UAAU,CAAC;QAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;QAC1C,+FAA+F;QAC/F,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;QACvD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB;;;;WAIG;QACH,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAiCD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAmOjE;AA2BD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,CAQrE"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/commands/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EACL,KAAK,UAAU,EAGf,KAAK,KAAK,EAEX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,CAAC,UAAU,EAAE;QACpB,KAAK,EAAE,UAAU,CAAC;QAClB,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;QAC1C,+FAA+F;QAC/F,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;QACvD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB;;;;WAIG;QACH,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAiCD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAoOjE;AA2BD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,CAQrE"}

package/dist/commands/dispatcher.js

@@ -70,6 +70,7 @@ export function createDispatcher(deps) {
                 const setupOptions = {
                     repository: issue.repository,
                     task: taskId,
+                    completionTaskId: issue.id,
                     agent: issue.agent,
                     details: {
                         title: issue.title,

package/dist/commands/resumeWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resumeWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/resumeWorkspace.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAcnE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAuID,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA2Ef;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}
+{"version":3,"file":"resumeWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/resumeWorkspace.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAenE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AA0ID,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Ef;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtE"}

package/dist/commands/resumeWorkspace.js

@@ -3,9 +3,10 @@ import { getLinearClient } from "../lib/adapters/linear/client.js";
 import { isLinearEnabled } from "../lib/buildSources.js";
 import { loadConfig } from "../lib/config.js";
 import { composeAgentLaunch, openAgentWorkspace, prepareAgentLaunch } from "../lib/agentLaunch.js";
+import { workerEnvironmentForTask } from "../lib/launchCommand.js";
 import { readRunState, recordRunState } from "../lib/runState.js";
 import { removeStagedPrompt, stageBuildSecrets, stagePromptText, stageWorkspaceLaunchCommand, } from "../lib/stagedLaunch.js";
-import { naturalIdFromCanonical } from "../lib/taskSource.js";
+import { naturalIdFromCanonical, toCanonicalId } from "../lib/taskSource.js";
 import { errorMessage, log } from "../lib/util.js";
 import { workspaces } from "../lib/workspaces.js";
 import { resolveLaunchDir, worktrees } from "../lib/worktrees.js";
@@ -38,6 +39,7 @@ async function contextFromLinear(config, task, worktree) {
         worktree,
         title: resolved.title,
         description: resolved.description,
+        completionTaskId: toCanonicalId("linear", task),
         resumeCount: 0,
     };
 }
@@ -53,6 +55,7 @@ async function contextFromState(config, task, state, worktree) {
         worktree,
         title: details?.title ?? task.toUpperCase(),
         description: details?.description ?? "",
+        completionTaskId: state.completionTaskId ?? task,
         ...(state.reason === undefined ? {} : { reason: state.reason }),
         resumeCount: state.resumeCount,
     };
@@ -147,6 +150,7 @@ export async function resumeWorkspace(config, options) {
             workingDir: launchDir,
             secretsFile,
             sandboxName,
+            workerEnvironment: workerEnvironmentForTask(context.completionTaskId),
         }));
         const launchCmd = stageWorkspaceLaunchCommand(stagedPrompt.directory, launchCommand);
         await openAgentWorkspace({
@@ -178,6 +182,7 @@ export async function resumeWorkspace(config, options) {
             workspaceName: task,
             state: "resumed",
             resumeCount: context.resumeCount + 1,
+            completionTaskId: context.completionTaskId,
             ...(context.reason === undefined ? {} : { reason: context.reason }),
         },
     });

package/dist/commands/setupWorkspace.d.ts

@@ -7,6 +7,8 @@ export interface TaskDetails {
 }
 export interface SetupWorkspaceOptions {
     task: string;
+    /** Canonical source id for worker self-completion; falls back to `task`. */
+    completionTaskId?: string;
     repository: string;
     agent: string;
     details: TaskDetails;

package/dist/commands/setupWorkspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAsBnE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA0Hf;AA8ID,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA4Cf"}
+{"version":3,"file":"setupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/setupWorkspace.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAuBnE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,GAAE,wBAA6B,GACxC,OAAO,CAAC,IAAI,CAAC,CA8Hf;AAgJD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,IAAI,CAAC,CA6Cf"}

package/dist/commands/setupWorkspace.js

@@ -3,6 +3,7 @@ import { loadConfig } from "../lib/config.js";
 import { composeAgentLaunch, openAgentWorkspace, prepareAgentLaunch } from "../lib/agentLaunch.js";
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
+import { workerEnvironmentForTask } from "../lib/launchCommand.js";
 import { resolvePrepareWorktreeCommand } from "../lib/repositoryHooks.js";
 import { recordRunState } from "../lib/runState.js";
 import { stageBuildSecrets, stagePromptFromTemplate, stageWorkspaceLaunchCommand, } from "../lib/stagedLaunch.js";
@@ -80,6 +81,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             defaultHooks: config.defaults.hooks,
         });
         const secretsFile = prepareWorktreeCommand === undefined ? undefined : stageBuildSecrets(promptDir);
+        const completionTaskId = options.completionTaskId ?? task;
         const { launchCommand, srtSettingsDir: stagedSrtSettingsDir } = composeAgentLaunch({
             runner,
             task,
@@ -90,6 +92,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             secretsFile,
             prepareWorktreeCommand,
             sandboxName,
+            workerEnvironment: workerEnvironmentForTask(completionTaskId),
         });
         srtSettingsDir = stagedSrtSettingsDir;
         const launchCmd = stageWorkspaceLaunchCommand(promptDir, launchCommand);
@@ -113,6 +116,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             workspaceName: task,
             state: "running",
             title: taskDetails.title,
+            completionTaskId,
             ...(taskDetails.url === undefined ? {} : { url: taskDetails.url }),
         });
         log(`${okMark()} "${task}" launched (${agent})  worktree ${worktreeName}`);
@@ -135,6 +139,7 @@ export async function setupWorkspace(config, options, runOptions = {}) {
             state: "failed-to-launch",
             detail: errorMessage(error),
             title: options.details.title,
+            completionTaskId: options.completionTaskId ?? task,
             ...(options.details.url === undefined ? {} : { url: options.details.url }),
         });
         throw error;
@@ -197,6 +202,7 @@ function recordRunStateBestEffort(arguments_) {
                 workspaceName: arguments_.workspaceName,
                 state: arguments_.state,
                 title: arguments_.title,
+                completionTaskId: arguments_.completionTaskId,
                 ...(arguments_.detail === undefined ? {} : { detail: arguments_.detail }),
                 ...(arguments_.url === undefined ? {} : { url: arguments_.url }),
             },
@@ -275,6 +281,7 @@ export async function setupWorkspaceCli(task, options = {}) {
     const naturalId = naturalIdFromCanonical(resolved.id);
     await setupWorkspace(config, {
         task: naturalId,
+        completionTaskId: resolved.id,
         repository: resolved.repository,
         agent: resolved.agent,
         details: {

package/dist/commands/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/commands/task.ts"],"names":[],"mappings":"AAmrBA,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB3D"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/commands/task.ts"],"names":[],"mappings":"AAoyBA,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB3D"}

package/dist/commands/task.js

@@ -1,13 +1,17 @@
+import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
 import { AGENT_ANY, loadConfig } from "../lib/config.js";
+import { findPullRequestsForBranch } from "../lib/pullRequests.js";
 import { naturalIdFromCanonical, } from "../lib/taskSource.js";
 import { parseSourceFilterArgs, writeOutput } from "../lib/util.js";
+import { worktrees } from "../lib/worktrees.js";
 const TASK_USAGE = `Usage: crew task <subcommand>
 
 Subcommands:
   list [options]                  List tasks across configured sources
   get <task-id> [options]         Get one task
   create "Short title" [options]  Create one task
+  done <task-id> [options]        Mark one task done
   validate [source] [options]     Validate task content`;
 const LIST_USAGE = `Usage: crew task list [options]
 
@@ -27,6 +31,7 @@ Options:
   --json           Print normalized task JSON.
   --prompt         Print only the task description/prompt.`;
 const CREATE_USAGE = `Usage: crew task create "Short title" --source <source> [--agent <agent>] [options]`;
+const DONE_USAGE = `Usage: crew task done <task-id> [--allow-dirty]`;
 const CANONICAL_STATUSES = [
     "todo",
     "in-progress",
@@ -251,10 +256,34 @@ function parseCreateOptions(argv) {
     };
     return { title, sourceName: state.sourceName, input, json: state.json };
 }
+function parseDoneOptions(argv) {
+    const positionals = [];
+    let allowDirty = false;
+    for (const argument of argv) {
+        if (argument === "--allow-dirty") {
+            allowDirty = true;
+            continue;
+        }
+        if (argument.startsWith("-")) {
+            throw new Error(`crew task done: unknown option: ${argument}\n${DONE_USAGE}`);
+        }
+        positionals.push(argument);
+    }
+    const [taskId, ...extras] = positionals;
+    if (taskId === undefined || taskId.length === 0 || extras.length > 0) {
+        throw new Error(DONE_USAGE);
+    }
+    return { taskId, allowDirty };
+}
 async function loadTaskSources() {
     const config = await loadConfig();
     return await buildSources(sourcesFromConfig(config), { globalConfig: config });
 }
+async function loadTaskBoard() {
+    const config = await loadConfig();
+    const sources = await buildSources(sourcesFromConfig(config), { globalConfig: config });
+    return { config, board: createBoard(sources) };
+}
 function findSource(sources, sourceName) {
     const source = sources.find((candidate) => candidate.name === sourceName);
     if (source === undefined) {
@@ -472,6 +501,60 @@ async function taskCreateCli(argv) {
     }
     writeOutput(created.id);
 }
+function matchingWorktreeEntries(arguments_) {
+    const task = naturalIdFromCanonical(arguments_.issue.id);
+    return worktrees
+        .findByTask(arguments_.config, task)
+        .filter((entry) => arguments_.issue.repository === undefined ||
+        entry.repository === arguments_.issue.repository);
+}
+function describeDirtiness(dirtiness) {
+    if (dirtiness.kind === "dirty") {
+        return `${dirtiness.modified} modified, ${dirtiness.untracked} untracked`;
+    }
+    return "unknown git status";
+}
+async function worktreeHasPullRequest(entry) {
+    const pullRequests = await findPullRequestsForBranch({
+        cwd: entry.dir,
+        branchName: entry.branchName,
+    });
+    return pullRequests.length > 0;
+}
+async function assertCanMarkDone(arguments_) {
+    if (arguments_.allowDirty) {
+        return;
+    }
+    for (const entry of matchingWorktreeEntries({
+        config: arguments_.config,
+        issue: arguments_.issue,
+    })) {
+        // oxlint-disable-next-line no-await-in-loop -- one git status per matching worktree keeps diagnostics deterministic.
+        const dirtiness = await worktrees.probeWorkingTree({ worktreeDir: entry.dir });
+        if (dirtiness.kind === "clean") {
+            continue;
+        }
+        // oxlint-disable-next-line no-await-in-loop -- only dirty/unknown worktrees need the PR lookup.
+        if (dirtiness.kind === "dirty" && (await worktreeHasPullRequest(entry))) {
+            continue;
+        }
+        throw new Error(`crew task done: refusing to mark ${arguments_.issue.id} done because ${entry.dir} has ${describeDirtiness(dirtiness)} and no matching PR. Commit or stash the work, open a PR, or rerun with --allow-dirty.`);
+    }
+}
+async function taskDoneCli(argv) {
+    const options = parseDoneOptions(argv);
+    const { config, board } = await loadTaskBoard();
+    const issue = await board.resolveOne(options.taskId);
+    if (issue === undefined) {
+        throw new Error(`Task ${options.taskId} not found across configured sources.`);
+    }
+    await assertCanMarkDone({ config, issue, allowDirty: options.allowDirty });
+    const result = await board.markDone(issue);
+    if (result.outcome === "unsupported") {
+        throw new Error(`crew task done: ${result.reason}`);
+    }
+    writeOutput(`Marked ${issue.id} done.`);
+}
 const VALIDATE_USAGE = `Usage: crew task validate [source]
 
 Options:
@@ -536,6 +619,10 @@ export async function taskCli(argv) {
         await taskCreateCli(rest);
         return;
     }
+    if (verb === "done") {
+        await taskDoneCli(rest);
+        return;
+    }
     if (verb === "validate") {
         await taskValidateCli(rest);
         return;

package/dist/lib/adapters/todo-txt/source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/todo-txt/source.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAoUxD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,cAAc,GACtB,UAAU,CAqKZ"}
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/todo-txt/source.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AA8VxD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,cAAc,GACtB,UAAU,CA2KZ"}

package/dist/lib/adapters/todo-txt/source.js

@@ -3,6 +3,7 @@ import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from
 import path from "node:path";
 import { AGENT_ANY } from "../../config.js";
 import { toCanonicalId, } from "../../taskSource.js";
+import { formatKnownRepositories } from "../../repositoryValidation.js";
 import { readEnvironmentVariable } from "../../util.js";
 import { isActiveForFetch, normalizeToIssue } from "./normalizer.js";
 import { DATE_RE, getMetadataFirst, parseAllLines } from "./parser.js";
@@ -161,6 +162,18 @@ function assertNewId(id, parsedAll) {
         throw new Error(`todo-txt: task id "${id}" already exists`);
     }
 }
+function assertCreateRepository(arguments_) {
+    const { defaultRepository, input, knownRepositories, sourceName } = arguments_;
+    const repository = input.repository ?? defaultRepository;
+    /* v8 ignore else @preserve -- both missing and resolved repository paths are covered; full-suite V8 coverage remaps the synthetic else inconsistently. */
+    if (repository === undefined) {
+        throw new Error(`todo-txt: --repo is required unless source "${sourceName}" configures defaultRepository. Known repositories: ${formatKnownRepositories(knownRepositories)}`);
+    }
+    /* v8 ignore else @preserve -- both known and unknown repository paths are covered; full-suite V8 coverage remaps the synthetic else inconsistently. */
+    if (!knownRepositories.includes(repository)) {
+        throw new Error(`todo-txt: repository "${repository}" is not in workspace.knownRepositories: ${formatKnownRepositories(knownRepositories)}`);
+    }
+}
 function buildTodoLine(id, input) {
     const title = input.title.trim();
     /* v8 ignore else @preserve -- no explicit else branch; full-suite V8 coverage remaps the synthetic else inconsistently. */
@@ -172,12 +185,14 @@ function buildTodoLine(id, input) {
         throw new Error("todo-txt: title must be a single line");
     }
     const tokens = [];
-    const priority = input.priority ?? "A";
-    /* v8 ignore else @preserve -- no explicit else branch; full-suite V8 coverage remaps the synthetic else inconsistently. */
-    if (!/^[A-Z]$/.test(priority)) {
-        throw new Error("todo-txt: priority must be a single uppercase letter");
+    /* v8 ignore else @preserve -- both priority-present and priority-absent creation paths are covered; full-suite V8 coverage remaps the synthetic else inconsistently. */
+    if (input.priority !== undefined) {
+        /* v8 ignore else @preserve -- no explicit else branch; full-suite V8 coverage remaps the synthetic else inconsistently. */
+        if (!/^[A-Z]$/.test(input.priority)) {
+            throw new Error("todo-txt: priority must be a single uppercase letter");
+        }
+        tokens.push(`(${input.priority})`);
     }
-    tokens.push(`(${priority})`);
     tokens.push(title);
     for (const rawProject of input.projects) {
         const project = normalizeProject(rawProject);
@@ -369,6 +384,12 @@ export function createTodoTxtTaskSource(config, context) {
                 const id = input.id ?? nextGeneratedId(config, parsedAll);
                 assertCreateId(id);
                 assertNewId(id, parsedAll);
+                assertCreateRepository({
+                    defaultRepository: config.defaultRepository,
+                    input,
+                    knownRepositories: context.globalConfig.workspace.knownRepositories,
+                    sourceName,
+                });
                 const promptPath = path.join(tasksDir, `${id}.md`);
                 const promptContent = promptContentFor(input);
                 const line = buildTodoLine(id, input);

package/dist/lib/agentLaunch.d.ts

@@ -1,4 +1,5 @@
 import { type LocalRunner, type AgentDefinition, type ResolvedConfig } from "./config.ts";
+import { type WorkerEnvironment } from "./launchCommand.ts";
 /**
  * Stage any srt settings and build the workspace launch command — the assembly
  * shared verbatim by `setupWorkspace` (fresh runs) and `resumeWorkspace`
@@ -16,6 +17,7 @@ export declare function composeAgentLaunch(input: {
     secretsFile?: string | undefined;
     prepareWorktreeCommand?: string | undefined;
     sandboxName?: string | undefined;
+    workerEnvironment?: WorkerEnvironment | undefined;
 }): {
     launchCommand: string;
     srtSettingsDir: string | undefined;

package/dist/lib/agentLaunch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/agentLaunch.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AASrB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CA0BhE;AAsBD,UAAU,mBAAmB;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA+C/B;AAwBD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB"}
+{"version":3,"file":"agentLaunch.d.ts","sourceRoot":"","sources":["../../src/lib/agentLaunch.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAOhF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACnD,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CA2BhE;AAsBD,UAAU,mBAAmB;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqD/B;AAwBD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB"}

package/dist/lib/agentLaunch.js

@@ -36,6 +36,7 @@ export function composeAgentLaunch(input) {
         srtAgentSettingsFile: staged?.agentFile,
         srtSettingsDir: staged?.directory,
         srtAgentConfigDirEnv: staged?.agentConfigDirEnv,
+        workerEnvironment: input.workerEnvironment,
         safehouseAddDirs: input.runner === "safehouse" ? resolveSafehouseAddDirs(input.worktreeDir) : undefined,
     });
     return { launchCommand, srtSettingsDir: staged?.directory };
@@ -88,6 +89,10 @@ export async function prepareAgentLaunch(input) {
         throw new Error(`Local groundcrew ${input.purpose} on agent '${input.agent}' cannot inject preLaunchEnv when 'cmd' already starts with 'safehouse'. ` +
             "Your cmd owns the wrap, so add the names to its own '--env-pass=' flag, or drop the 'safehouse' prefix from 'cmd' to let groundcrew compose the flag for you.");
     }
+    if (runner === "safehouse" && /^safehouse(?:\s|$)/.test(input.definition.cmd)) {
+        throw new Error(`Local groundcrew ${input.purpose} on agent '${input.agent}' cannot inject worker self-completion env when 'cmd' already starts with 'safehouse'. ` +
+            "Your cmd owns the wrap, so add GROUNDCREW_TASK_ID,GROUNDCREW_COMPLETE to its own '--env-pass=' flag, or drop the 'safehouse' prefix from 'cmd' to let groundcrew compose the flag for you.");
+    }
     const sandboxName = runner === "sdx" && input.definition.sandbox !== undefined
         ? sandboxNameFor({ agent: input.definition.sandbox.agent })
         : undefined;

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}

package/dist/lib/config.js

@@ -108,6 +108,7 @@ const DEFAULT_PROMPT_INITIAL = [
     "2. Implement the smallest sensible change that completes the task.",
     "3. Run the repo's documented verification command. If no documented command exists, run the smallest relevant test suite you can find and fix failures you introduced before continuing.",
     "4. Follow the task description for output. If no output instructions exist, open a PR with `Closes {{task}}` in the description. If you cannot open one, leave the branch ready and record the blocker.",
+    "5. If the requested work is complete, no PR is needed, and any dirty worktree state is expected or explicitly allowed, run the command in `GROUNDCREW_COMPLETE` to mark the task done.",
 ].join("\n");
 const ALLOWED_PROMPT_PLACEHOLDERS = new Set([
     "{{task}}",

package/dist/lib/launchCommand.d.ts

@@ -37,6 +37,10 @@ export declare function isEnvironmentAssignment(token: string): boolean;
  * profile; srt uses it to pick the agent's credential profile in `srtPolicy`.
  */
 export declare function inferAgentCommandName(agentCmd: string): string;
+declare const WORKER_ENVIRONMENT_NAMES: readonly ["GROUNDCREW_TASK_ID", "GROUNDCREW_COMPLETE"];
+type WorkerEnvironmentName = (typeof WORKER_ENVIRONMENT_NAMES)[number];
+export type WorkerEnvironment = Readonly<Record<WorkerEnvironmentName, string>>;
+export declare function workerEnvironmentForTask(taskId: string): WorkerEnvironment;
 interface LaunchCommandArguments {
     definition: AgentDefinition;
     promptFile: string;
@@ -111,6 +115,11 @@ interface LaunchCommandArguments {
      * pre-existing behavior). Only consumed by the safehouse wrap.
      */
     safehouseAddDirs?: readonly string[] | undefined;
+    /**
+     * Groundcrew-managed task metadata exposed to the launched worker. Forwarded
+     * to the agent process, not the prepareWorktree hook.
+     */
+    workerEnvironment?: WorkerEnvironment | undefined;
 }
 /**
  * Build the shell command that runs inside the workspace. The prompt is

package/dist/lib/launchCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAgB3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAMvF;AAsMD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8B9D;AAED,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CA6B7E"}
+{"version":3,"file":"launchCommand.d.ts","sourceRoot":"","sources":["../../src/lib/launchCommand.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAcvF;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,MAAwB,GAAG,MAAM,CAgB3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAMvF;AAsMD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8B9D;AAED,QAAA,MAAM,wBAAwB,YAAI,oBAAoB,EAAE,qBAAqB,CAAU,CAAC;AAExF,KAAK,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAK1E;AAsBD,UAAU,sBAAsB;IAC9B,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACjD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CAkC7E"}

package/dist/lib/launchCommand.js

@@ -247,6 +247,26 @@ export function inferAgentCommandName(agentCmd) {
     }
     return commandName;
 }
+const WORKER_ENVIRONMENT_NAMES = ["GROUNDCREW_TASK_ID", "GROUNDCREW_COMPLETE"];
+export function workerEnvironmentForTask(taskId) {
+    return {
+        GROUNDCREW_TASK_ID: taskId,
+        GROUNDCREW_COMPLETE: `crew task done ${taskId}`,
+    };
+}
+function workerEnvironmentNames(workerEnvironment) {
+    return workerEnvironment === undefined ? [] : WORKER_ENVIRONMENT_NAMES;
+}
+function workerEnvironmentExports(workerEnvironment) {
+    if (workerEnvironment === undefined) {
+        return [];
+    }
+    return WORKER_ENVIRONMENT_NAMES.map((name) => `export ${name}=${shellSingleQuote(workerEnvironment[name])}`);
+}
+function envPassFlag(names) {
+    const uniqueNames = [...new Set(names)];
+    return uniqueNames.length === 0 ? "" : `--env-pass=${uniqueNames.join(",")} `;
+}
 /**
  * Build the shell command that runs inside the workspace. The prompt is
  * staged in a temp file (so backticks/quotes/$ in the description survive),
@@ -277,6 +297,9 @@ export function buildLaunchCommand(arguments_) {
         // inject into. Fail loudly instead of silently dropping the contract.
         throw new Error("preLaunchEnv cannot be injected when `cmd` starts with `safehouse` — your cmd owns the wrap, so add the names to its own `--env-pass=` flag, or drop the `safehouse` prefix from `cmd` to let groundcrew compose the flag for you.");
     }
+    if (arguments_.workerEnvironment !== undefined && arguments_.runner === "safehouse") {
+        throw new Error("workerEnvironment cannot be injected when `cmd` starts with `safehouse` — your cmd owns the wrap, so add GROUNDCREW_TASK_ID,GROUNDCREW_COMPLETE to its own `--env-pass=` flag, or drop the `safehouse` prefix from `cmd` to let groundcrew compose the flag for you.");
+    }
     return buildUnwrappedHostLaunchCommand(arguments_);
 }
 /**
@@ -315,6 +338,7 @@ function buildUnwrappedHostLaunchCommand(arguments_) {
     if (arguments_.secretsFile !== undefined) {
         lines.push(unsetSecretsLine());
     }
+    lines.push(...workerEnvironmentExports(arguments_.workerEnvironment));
     lines.push(...preLaunchPromptAndExec({
         definition: arguments_.definition,
         worktreeDir: arguments_.worktreeDir,
@@ -365,8 +389,10 @@ function buildSafehouseLaunchCommand(arguments_) {
     // credentials out of the profile-neutral prepare phase — see PR #128.
     // Trailing space keeps each flag separated from the next argv token.
     const prepareWorktreeEnvPassFlag = arguments_.secretsFile === undefined ? "" : `--env-pass=${BUILD_SECRET_NAMES.join(",")} `;
-    const preLaunchEnvNames = arguments_.definition.preLaunchEnv ?? [];
-    const agentEnvPassFlag = preLaunchEnvNames.length === 0 ? "" : `--env-pass=${preLaunchEnvNames.join(",")} `;
+    const agentEnvPassFlag = envPassFlag([
+        ...(arguments_.definition.preLaunchEnv ?? []),
+        ...workerEnvironmentNames(arguments_.workerEnvironment),
+    ]);
     // safehouse reads colon-separated paths from `--add-dirs`; both wraps get the
     // same grant so the prepareWorktree hook and the agent can each reach git.
     // Quote the whole value so shell-special chars survive; the trailing space
@@ -398,7 +424,7 @@ function buildSafehouseLaunchCommand(arguments_) {
     if (arguments_.secretsFile !== undefined) {
         lines.push(unsetSecretsLine());
     }
-    lines.push(`_safehouse_shim_dir=$(mktemp -d "\${TMPDIR:-/tmp}/groundcrew-safehouse-XXXXXX")`, shimAndPromptTrap, `_safehouse_shim="$_safehouse_shim_dir/${safehouseCommandName}"`, `ln -s /bin/sh "$_safehouse_shim"`, 
+    lines.push(...workerEnvironmentExports(arguments_.workerEnvironment), `_safehouse_shim_dir=$(mktemp -d "\${TMPDIR:-/tmp}/groundcrew-safehouse-XXXXXX")`, shimAndPromptTrap, `_safehouse_shim="$_safehouse_shim_dir/${safehouseCommandName}"`, `ln -s /bin/sh "$_safehouse_shim"`, 
     // Safehouse selects an agent profile from the wrapped command's basename.
     // Running the real launch chain as `sh -c` would make it see `sh`, so use
     // an agent-named symlink to /bin/sh. This preserves per-agent profile
@@ -492,7 +518,10 @@ function buildSrtLaunchCommand(arguments_) {
     const agentConfigDirAssignment = arguments_.srtAgentConfigDirEnv === undefined
         ? ""
         : ` ${arguments_.srtAgentConfigDirEnv.name}=${shellSingleQuote(arguments_.srtAgentConfigDirEnv.value)}`;
-    const agentWrap = `env -i ${baseline}${agentConfigDirAssignment}${srtForwardedEnv(arguments_.definition.preLaunchEnv ?? [])} ${agentTarget}`;
+    const agentWrap = `env -i ${baseline}${agentConfigDirAssignment}${srtForwardedEnv([
+        ...(arguments_.definition.preLaunchEnv ?? []),
+        ...workerEnvironmentNames(arguments_.workerEnvironment),
+    ])} ${agentTarget}`;
     // One EXIT trap wipes both the settings dir and the prompt dir, covering
     // every failure window between here and the post-wrap cleanup.
     const cleanup = `rm -rf ${shellSingleQuote(arguments_.srtSettingsDir)}; rm -rf ${shellSingleQuote(promptDir)}`;
@@ -510,7 +539,7 @@ function buildSrtLaunchCommand(arguments_) {
     if (prepareWorktreeCommand !== undefined) {
         lines.push(`${prepareWrap} sh -c ${shellSingleQuote(prepareWorktreeCommand)}`);
     }
-    lines.push(`{ ${agentWrap} sh -c ${shellSingleQuote(agentCommand)} sh "$_p"; _srt_status=$?; rm -rf ${shellSingleQuote(arguments_.srtSettingsDir)}; trap - EXIT; exit "$_srt_status"; }`);
+    lines.push(...workerEnvironmentExports(arguments_.workerEnvironment), `{ ${agentWrap} sh -c ${shellSingleQuote(agentCommand)} sh "$_p"; _srt_status=$?; rm -rf ${shellSingleQuote(arguments_.srtSettingsDir)}; trap - EXIT; exit "$_srt_status"; }`);
     return lines.join(" && ");
 }
 function buildSdxLaunchCommand(arguments_) {
@@ -527,15 +556,17 @@ function buildSdxLaunchCommand(arguments_) {
     if (arguments_.secretsFile !== undefined) {
         innerParts.push(unsetSecretsLine());
     }
+    innerParts.push(...workerEnvironmentExports(arguments_.workerEnvironment));
     innerParts.push(agentCommand);
     const innerCommand = innerParts.join("; ");
     // Passthrough form (`-e KEY` without `=VALUE`): sbx reads each value
     // from its own env at invocation time — populated by sourceSecretsLine
     // a few lines up. Avoids `-e KEY="$KEY"`, which would embed the value
     // in argv and break on `"`, `$`, or backticks in the token.
-    const sbxEnvironmentFlags = arguments_.secretsFile === undefined
+    const sbxEnvironmentNames = arguments_.secretsFile === undefined ? [] : BUILD_SECRET_NAMES;
+    const sbxEnvironmentFlags = sbxEnvironmentNames.length === 0
         ? ""
-        : `${BUILD_SECRET_NAMES.map((name) => `-e ${name}`).join(" ")} `;
+        : `${sbxEnvironmentNames.map((name) => `-e ${name}`).join(" ")} `;
     const lines = [trapCleanupLine(promptDir)];
     if (arguments_.secretsFile !== undefined) {
         lines.push(sourceSecretsLine(arguments_.secretsFile));

package/dist/lib/runState.d.ts

@@ -26,6 +26,11 @@ export interface RunState {
      * just the task id.
      */
     url?: string;
+    /**
+     * Canonical source-prefixed id used for no-PR self-completion. Cached so
+     * resumed workers keep the same completion target as the original launch.
+     */
+    completionTaskId?: string;
 }
 export interface RunStateDraft {
     task: string;
@@ -40,6 +45,7 @@ export interface RunStateDraft {
     resumeCount?: number;
     title?: string;
     url?: string;
+    completionTaskId?: string;
 }
 export interface RecordRunStateInput {
     config: ResolvedConfig;

package/dist/lib/runState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runState.d.ts","sourceRoot":"","sources":["../../src/lib/runState.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAE3F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAAC,CAAC,GAAG;QACrD,KAAK,EAAE,iBAAiB,CAAC;KAC1B,CAAC;CACH;AAQD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,MAAM,CAEjF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAmFD,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAYvF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,QAAQ,CA0BnE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,QAAQ,GAAG,SAAS,CAc/E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzE"}
+{"version":3,"file":"runState.d.ts","sourceRoot":"","sources":["../../src/lib/runState.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAE3F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAAC,CAAC,GAAG;QACrD,KAAK,EAAE,iBAAiB,CAAC;KAC1B,CAAC;CACH;AAQD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,MAAM,CAEjF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAqFD,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAYvF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,QAAQ,CA4BnE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,QAAQ,GAAG,SAAS,CAc/E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzE"}

package/dist/lib/runState.js

@@ -44,6 +44,7 @@ function parseRunState(value) {
     const detail = stringField(value, "detail");
     const title = stringField(value, "title");
     const url = stringField(value, "url");
+    const completionTaskId = stringField(value, "completionTaskId");
     if (task === undefined ||
         repository === undefined ||
         agent === undefined ||
@@ -73,6 +74,7 @@ function parseRunState(value) {
         ...(detail === undefined ? {} : { detail }),
         ...(title === undefined ? {} : { title }),
         ...(url === undefined ? {} : { url }),
+        ...(completionTaskId === undefined ? {} : { completionTaskId }),
     };
 }
 function writeState(config, state) {
@@ -105,6 +107,7 @@ export function recordRunState(input) {
     // transitions.
     const title = input.state.title ?? existing?.title;
     const url = input.state.url ?? existing?.url;
+    const completionTaskId = input.state.completionTaskId ?? existing?.completionTaskId;
     const state = {
         task: taskKey(input.state.task),
         repository: input.state.repository,
@@ -120,6 +123,7 @@ export function recordRunState(input) {
         ...(input.state.detail === undefined ? {} : { detail: input.state.detail }),
         ...(title === undefined ? {} : { title }),
         ...(url === undefined ? {} : { url }),
+        ...(completionTaskId === undefined ? {} : { completionTaskId }),
     };
     writeState(input.config, state);
     return state;

package/docs/commands.md

@@ -18,7 +18,7 @@ crew task get GC-20260608-001 --source todo
 crew task get todo:GC-20260608-001 --prompt
 ```
 
-`crew task create "Short title" --source <source> [--agent <agent>]` creates a task in a source that supports creation. When `--agent` is omitted, it defaults to `any`. Todo.txt creation appends the todo line, defaults to priority `A` unless `--priority` is provided, writes `.tasks/<id>.md`, and leaves `status:todo` as the final meaningful token, so no separate ready command is required. Hand-written todo-txt lines can omit `.tasks/<id>.md` when the line has a non-empty title; that title becomes the prompt text.
+`crew task create "Short title" --source <source> [--agent <agent>]` creates a task in a source that supports creation. When `--agent` is omitted, it defaults to `any`. Todo.txt creation requires `--repo <repo>` unless the source configures `defaultRepository`, appends the todo line, writes `.tasks/<id>.md`, and leaves `status:todo` as the final meaningful token, so no separate ready command is required. Pass `--priority <letter>` to add a todo.txt priority marker. Hand-written todo-txt lines can omit `.tasks/<id>.md` when the line has a non-empty title; that title becomes the prompt text.
 
 ```bash
 crew task create "Fix cancellation retry race" \
@@ -41,6 +41,44 @@ crew task create "Fix cancellation retry race" \
   --description "Investigate retry handling."
 ```
 
+`crew task done <task-id>` marks one task done through its source adapter. Use
+it for completed work that intentionally does not produce a PR. The command
+resolves canonical IDs such as `todo:flaky-triage-1` directly, or natural IDs
+when they match exactly one configured source. Sources without a done writeback
+return an unsupported error.
+
+Groundcrew checks matching local worktrees before marking a task done. Clean
+worktrees, and tasks with no local worktree, are allowed. A dirty worktree with
+no matching PR is refused by default so later cleanup does not discard
+uncommitted work; pass `--allow-dirty` only when that dirty state is expected.
+
+```bash
+# PR-producing tasks usually complete automatically:
+# open PR -> in-review, merged PR -> done.
+
+# Manual completion for no-PR operational work:
+crew task done todo:flaky-triage-1
+
+# Explicit override when a no-PR task intentionally leaves local changes:
+crew task done todo:docs-refresh-1 --allow-dirty
+```
+
+For recurring no-PR tasks, keep recurrence in the source and complete the
+current task with `crew task done`. The todo-txt source marks the current line
+done and schedules the next `status:todo` recurrence itself.
+
+```bash
+crew task create "Run flaky triage sweep" \
+  --source todo \
+  --agent codex \
+  --repo ClipboardHealth/groundcrew \
+  --id flaky-triage-1 \
+  --rec 2h \
+  --description "Triage the flaky queue. No PR is needed when the queue is updated."
+
+crew task done todo:flaky-triage-1
+```
+
 ## Status
 
 `crew status <TASK>` prints a read-only snapshot for one task: cached title and URL when present, recorded run state, live workspace presence, matching worktrees, git dirtiness, PR links for matching branches, recent log lines when present, and the task status from the configured task source.
@@ -57,7 +95,7 @@ crew status ENG-123
 ===================
 task: eng-123  in-progress  https://linear.app/example/issue/ENG-123
 title: Multi-event extractor: year inference can produce date_start > date_end
-run: running; model=claude; updated=2026-05-26T00:01:00.000Z; resumes=0
+run: running; agent=claude; updated=2026-05-26T00:01:00.000Z; resumes=0
 workspace: live
 
 Worktrees
@@ -77,9 +115,9 @@ Recent logs
 
 ## Doctor
 
-`crew doctor` checks host prerequisites only: config validity, task-source reachability, required binaries on PATH, workspace backend availability, `workspace.projectDir`, local runner capability, and enabled model commands.
+`crew doctor` checks host prerequisites only: config validity, task-source reachability, required binaries on PATH, workspace backend availability, `workspace.projectDir`, local runner capability, and enabled agent commands.
 
-Doctor's command introspection is intentionally shallow. It reports the resolved local runner and tokenizes each model `cmd`, then checks the first two non-flag tokens against PATH. Boolean flags without values, env-var assignments, shell pipelines, and subshells are not parsed.
+Doctor's command introspection is intentionally shallow. It reports the resolved local runner and tokenizes each agent `cmd`, then checks the first two non-flag tokens against PATH. Boolean flags without values, env-var assignments, shell pipelines, and subshells are not parsed.
 
 ## Start
 
@@ -106,4 +144,4 @@ The command closes the cmux/tmux/zellij workspace if present, records local run
 
 `crew resume <TASK>` reopens an existing task worktree with a continuation prompt. Resume never creates a new worktree; if none exists it fails and leaves re-dispatch to `crew start <task>`.
 
-The resume prompt tells the agent to inspect git status and diff before editing, includes the previous interrupt reason when recorded, and reuses the recorded model, repository, branch, runner, sandbox, and workspace backend. When no run-state file exists but a worktree does, resume falls back to Linear resolution for the model and task context.
+The resume prompt tells the agent to inspect git status and diff before editing, includes the previous interrupt reason when recorded, and reuses the recorded agent, repository, branch, runner, sandbox, and workspace backend. When no run-state file exists but a worktree does, resume falls back to Linear resolution for the agent and task context.

package/docs/configuration.md

@@ -1,13 +1,13 @@
 # Configuration
 
-Workspace settings and at least one enabled model are required; everything else has a default.
+Workspace settings and at least one enabled agent are required; everything else has a default.
 
 | Key                           | What                                                                 |
 | ----------------------------- | -------------------------------------------------------------------- |
 | `workspace.projectDir`        | Parent dir for cloned repos and the default task worktree root.      |
 | `workspace.worktreeDir`       | Optional parent dir for task worktrees.                              |
 | `workspace.knownRepositories` | Repos searched for in task descriptions to infer where work belongs. |
-| `models.definitions`          | Enabled model set. Built-in presets can be enabled with `{}`.        |
+| `agents.definitions`          | Enabled agent set. Built-in presets can be enabled with `{}`.        |
 
 The branch prefix (`<prefix>-<TASK>`) defaults to `os.userInfo().username`; override it with `git.branchPrefix` (see the full reference below). Changing it only affects newly created worktrees; existing local branches keep their original names until cleaned up. Groundcrew picks up every issue assigned to your API key's viewer that carries an `agent-*` label across every visible team and project, governed by a single `orchestrator.maximumInProgress` budget.
 
@@ -92,11 +92,11 @@ The "Loaded config from ..." line at startup tells you which config won.
 
 ## Agent Label Routing
 
-- `agent-claude`, `agent-codex`, `agent-<name>` routes to that enabled model.
-- `agent-any` routes to the model with the most session headroom, after skipping models over their session limit or weekly paced budget.
-- Unknown `agent-<name>` falls back to `models.default`.
-- A built-in `agent-<name>` label whose model is not enabled falls back to `models.default` with a warning.
-- No `agent-*` label is ignored by `crew run`. Dispatch on demand with `crew start <TASK>`, which falls back to `models.default`.
+- `agent-claude`, `agent-codex`, `agent-<name>` routes to that enabled agent.
+- `agent-any` routes to the agent with the most session headroom, after skipping agents over their session limit or weekly paced budget.
+- Unknown `agent-<name>` falls back to `agents.default`.
+- A built-in `agent-<name>` label whose agent is not enabled falls back to `agents.default` with a warning.
+- No `agent-*` label is ignored by `crew run`. Dispatch on demand with `crew start <TASK>`, which falls back to `agents.default`.
 - Todo tasks blocked by non-terminal blockers are skipped until their blockers reach a terminal status.
 
 Status classification uses Linear's default status names `In Progress` and `In Review` to disambiguate multiple `started` workflow states. Statuses that do not match those names fall back to Linear's workflow `state.type` (`unstarted`, `started`, `completed`, `canceled`, `duplicate`), so broad lifecycle classification still works without configuration. Parent issues with children are ignored; sub-issues are the work items.
@@ -136,13 +136,13 @@ export default {
 };
 ```
 
-## Enabling Model Presets
+## Enabling Agent Presets
 
-Groundcrew ships built-in presets for `claude` and `codex`, but models are not enabled by default. List the models you want in `models.definitions`:
+Groundcrew ships built-in presets for `claude` and `codex`, but agents are not enabled by default. List the agents you want in `agents.definitions`:
 
 ```ts
 export default {
-  models: {
+  agents: {
     default: "claude",
     definitions: {
       claude: {},
@@ -155,7 +155,7 @@ To keep both shipped presets enabled:
 
 ```ts
 export default {
-  models: {
+  agents: {
     default: "claude",
     definitions: {
       claude: {},
@@ -167,15 +167,15 @@ export default {
 
 Rules:
 
-- `models.definitions` is the enabled model set; `crew doctor` only probes listed models.
+- `agents.definitions` is the enabled agent set; `crew doctor` only probes listed agents.
 - Built-in entries can be `{}` or partial overrides such as `{ cmd: "..." }`.
-- Custom model names must provide `cmd` and `color`.
-- `models.default` must point at an enabled model.
-- Legacy model entries like `codex: { disabled: true }` are rejected with migration guidance; remove unwanted entries instead.
+- Custom agent names must provide `cmd` and `color`.
+- `agents.default` must point at an enabled agent.
+- Legacy agent entries like `codex: { disabled: true }` are rejected with migration guidance; remove unwanted entries instead.
 
 ## Prompt Customization
 
-Groundcrew ships one model-agnostic unattended prompt by default. It tells the agent to make reasonable assumptions, follow repository instructions, run documented verification, review its diff, open a PR when GitHub/`gh` is available, and include a workspace continuation hint when known.
+Groundcrew ships one agent-agnostic unattended prompt by default. It tells the agent to make reasonable assumptions, follow repository instructions, run documented verification, review its diff, open a PR when GitHub/`gh` is available, and include a workspace continuation hint when known.
 
 This prompt describes how the agent works, not what it does. The task is the task description, which groundcrew passes through unchanged. Keep source-specific instructions, acceptance criteria, links, and output requirements in the task body. Override `prompts.initial` only to change the execution contract for every dispatched task — team-wide review rules, required verification, local tool conventions — not to encode behavior for a single task type.
 
@@ -242,15 +242,15 @@ and hook contract.
 | `defaults.hooks.prepareWorktree`         | optional             | Fallback repo-preparation command used only when the worktree does not define `.groundcrew/config.json` `hooks.prepareWorktree`. The hook runs after worktree creation and before the agent starts. Repo-local config wins.                                                                                                                                                                                                                                                                                                 |
 | `orchestrator.maximumInProgress`         | `4`                  | Cap on in-progress tasks at once for this `crew` instance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `orchestrator.pollIntervalMilliseconds`  | `120_000`            | Poll interval in `--watch` mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `orchestrator.sessionLimitPercentage`    | `85`                 | Number in `(0, 100]`. A model whose codexbar session window exceeds this percentage is skipped that tick. Models are also skipped when codexbar reports weekly usage over the current weekly paced budget.                                                                                                                                                                                                                                                                                                                  |
-| `models.default`                         | `"claude"`           | Tiebreak for `agent-any` resolution and fallback for explicit but unknown `agent-*` labels. Also used by `crew start <TASK>` for unlabeled tasks. `crew run` ignores unlabeled tasks and does not apply this default. Must exist in `models.definitions`. If you enable only `codex`, set `default: "codex"`.                                                                                                                                                                                                               |
-| `models.definitions`                     | **required**         | Enabled model set. Built-in keys (`claude`, `codex`) can use `{}` to opt into the shipped preset. Custom model names must provide `cmd` and `color`.                                                                                                                                                                                                                                                                                                                                                                        |
-| `models.definitions.<name>.cmd`          | preset for built-ins | Shell command launched for the model. Required for custom models. Runs in the worktree through the resolved `local.runner`. `{{worktree}}` is replaced before launch; `{{sandbox}}` expands to the sbx sandbox name under the sdx runner and an empty string otherwise.                                                                                                                                                                                                                                                     |
-| `models.definitions.<name>.color`        | preset for built-ins | Color for the workspace status pill (cmux only; tmux and zellij silently drop it). Required for custom models.                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `models.definitions.<name>.usage`        | preset for built-ins | If set, codexbar usage is fetched for this model and gated by `sessionLimitPercentage` plus the weekly paced budget when codexbar exposes a weekly window. When `usage.codexbar.source` is omitted, groundcrew uses `oauth` for Codex/Claude on macOS, `auto` for other macOS providers, and `cli` elsewhere. Set to `{ disabled: true }` to disable usage gating while keeping the model enabled.                                                                                                                          |
-| `models.definitions.<name>.sandbox`      | optional             | Docker Sandboxes binding for the model. Required at launch when `local.runner` resolves to `sdx`. Field: `agent` (required sbx agent name). Groundcrew assumes the `groundcrew-<agent>` sandbox already exists.                                                                                                                                                                                                                                                                                                             |
-| `models.definitions.<name>.preLaunch`    | optional             | Host-only shell snippet run before the agent exec and outside Safehouse/sdx. Exports survive into the launch shell; under the default `safehouse` runner they are only forwarded to the agent when listed via `preLaunchEnv` or when `cmd` includes its own `safehouse --env-pass=NAMES`. `{{worktree}}` is substituted. A non-zero exit aborts launch. Not supported when `local.runner` resolves to `sdx` in v1.                                                                                                          |
-| `models.definitions.<name>.preLaunchEnv` | optional             | Companion to `preLaunch`: list of env var names to append to groundcrew's `safehouse-clearance` `--env-pass=` flag, so `preLaunch` exports reach the agent without overriding `cmd` and losing the project's egress allowlist. Each entry must match `[A-Za-z_][A-Za-z0-9_]*`. Under `runner: "none"` exports already inherit and `preLaunchEnv` is a no-op. An empty array is a uniform no-op in every runner; a non-empty list is rejected when `cmd` already starts with `safehouse` or when `runner` resolves to `sdx`. |
+| `orchestrator.sessionLimitPercentage`    | `85`                 | Number in `(0, 100]`. An agent whose codexbar session window exceeds this percentage is skipped that tick. Agents are also skipped when codexbar reports weekly usage over the current weekly paced budget.                                                                                                                                                                                                                                                                                                                 |
+| `agents.default`                         | `"claude"`           | Tiebreak for `agent-any` resolution and fallback for explicit but unknown `agent-*` labels. Also used by `crew start <TASK>` for unlabeled tasks. `crew run` ignores unlabeled tasks and does not apply this default. Must exist in `agents.definitions`. If you enable only `codex`, set `default: "codex"`.                                                                                                                                                                                                               |
+| `agents.definitions`                     | **required**         | Enabled agent set. Built-in keys (`claude`, `codex`) can use `{}` to opt into the shipped preset. Custom agent names must provide `cmd` and `color`.                                                                                                                                                                                                                                                                                                                                                                        |
+| `agents.definitions.<name>.cmd`          | preset for built-ins | Shell command launched for the agent. Required for custom agents. Runs in the worktree through the resolved `local.runner`. `{{worktree}}` is replaced before launch; `{{sandbox}}` expands to the sbx sandbox name under the sdx runner and an empty string otherwise.                                                                                                                                                                                                                                                     |
+| `agents.definitions.<name>.color`        | preset for built-ins | Color for the workspace status pill (cmux only; tmux and zellij silently drop it). Required for custom agents.                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `agents.definitions.<name>.usage`        | preset for built-ins | If set, codexbar usage is fetched for this agent and gated by `sessionLimitPercentage` plus the weekly paced budget when codexbar exposes a weekly window. When `usage.codexbar.source` is omitted, groundcrew uses `oauth` for Codex/Claude on macOS, `auto` for other macOS providers, and `cli` elsewhere. Set to `{ disabled: true }` to disable usage gating while keeping the agent enabled.                                                                                                                          |
+| `agents.definitions.<name>.sandbox`      | optional             | Docker Sandboxes binding for the agent. Required at launch when `local.runner` resolves to `sdx`. Field: `agent` (required sbx agent name). Groundcrew assumes the `groundcrew-<agent>` sandbox already exists.                                                                                                                                                                                                                                                                                                             |
+| `agents.definitions.<name>.preLaunch`    | optional             | Host-only shell snippet run before the agent exec and outside Safehouse/sdx. Exports survive into the launch shell; under the default `safehouse` runner they are only forwarded to the agent when listed via `preLaunchEnv` or when `cmd` includes its own `safehouse --env-pass=NAMES`. `{{worktree}}` is substituted. A non-zero exit aborts launch. Not supported when `local.runner` resolves to `sdx` in v1.                                                                                                          |
+| `agents.definitions.<name>.preLaunchEnv` | optional             | Companion to `preLaunch`: list of env var names to append to groundcrew's `safehouse-clearance` `--env-pass=` flag, so `preLaunch` exports reach the agent without overriding `cmd` and losing the project's egress allowlist. Each entry must match `[A-Za-z_][A-Za-z0-9_]*`. Under `runner: "none"` exports already inherit and `preLaunchEnv` is a no-op. An empty array is a uniform no-op in every runner; a non-empty list is rejected when `cmd` already starts with `safehouse` or when `runner` resolves to `sdx`. |
 | `prompts.initial`                        | unattended template  | First message sent to the agent: the execution wrapper around each task. The task description is the task-specific prompt. Placeholders: `{{task}}`, `{{worktree}}`, `{{title}}`, `{{description}}`. Override only to change the execution contract for every task, such as team-wide review rules or tool conventions. Mutually exclusive with `prompts.promptFile`.                                                                                                                                                       |
 | `prompts.promptFile`                     | optional             | Path to a UTF-8 file whose contents become `prompts.initial`, read at load time. Resolved relative to the config file's directory; `~` is expanded and absolute paths are used as-is. The JSON-friendly alternative to inlining a large prompt or `readFileSync`. Mutually exclusive with `prompts.initial`.                                                                                                                                                                                                                |
 | `workspaceKind`                          | `"auto"`             | Terminal session manager. `"auto"` picks `cmux` when on PATH, else `tmux`. Set to `"cmux"`, `"tmux"`, or `"zellij"` to fail loudly when the chosen backend is missing.                                                                                                                                                                                                                                                                                                                                                      |

package/docs/credentials.md

@@ -52,7 +52,7 @@ The "preLaunch never sees build secrets" contract is enforced differently per ru
 Under the default `safehouse` runner, the agent runs under a sanitized env allowlist. Exports from `preLaunch` land in the launch shell but are stripped before reaching the agent unless they are forwarded. `preLaunchEnv` is the supported way to forward them:
 
 ```ts
-models: {
+agents: {
   definitions: {
     claude: {
       preLaunch: "SESSION_TOKEN=$(your-mint-command) && export SESSION_TOKEN",
@@ -69,7 +69,7 @@ Under `runner: "none"`, exports flow through unchanged and `preLaunchEnv` is a n
 <details>
 <summary>Manual fallback when <code>cmd</code> brings its own <code>safehouse</code> wrap</summary>
 
-If your `cmd` already starts with `safehouse`, groundcrew will not auto-compose `--env-pass=` for you and a non-empty `preLaunchEnv` is rejected at launch. Add the names to your own `cmd` instead. This opts the model out of groundcrew's default `safehouse-clearance` wrap, so re-supply `--append-profile` / `--env` yourself if you need it:
+If your `cmd` already starts with `safehouse`, groundcrew will not auto-compose `--env-pass=` for you and a non-empty `preLaunchEnv` is rejected at launch. Add the names to your own `cmd` instead. This opts the agent out of groundcrew's default `safehouse-clearance` wrap, so re-supply `--append-profile` / `--env` yourself if you need it:
 
 ```ts
 claude: {

package/docs/runners.md

@@ -49,7 +49,7 @@ Groundcrew generates a per-launch policy itself (Safehouse's `.sb` profiles have
 
 - **Reads**: the home region (`/Users` on macOS, `/home`+`/root`+`/mnt` on Linux — `/mnt` covers WSL's Windows drive mounts) is denied, then the worktree, the repo's git metadata, the language toolchains needed to run the agent, and the agent's own config dirs (`~/.claude`, `~/.codex`, …) are re-opened. On macOS the user keychain dir (`~/Library/Keychains`) is also re-opened read-only so keychain-authenticated agents (claude) can sign in under the home mask. The agent cannot read `~/.ssh`, `~/.aws`, shell history, or unrelated repos.
 - **Writes**: allow-only, and the host-CLI persistence vector (planting hooks, `mcpServers`, `commands/`, `plugins/`, … that run on the user's next host invocation) is closed per agent. **claude** keeps a writable `~/.claude` (its Bash tool needs scratch/session state there) but every fixed-path executable/instruction surface — `~/.claude.json` (`mcpServers`), `settings.json` and its hooks, `commands/`, `agents/`, `plugins/`, `skills/`, `statusline.sh`, `CLAUDE.md`, the bundled `chrome` binary, `.git/{hooks,config}` — is denied; claude tolerates those write denials. **codex** hard-fails with a read-only home, so it is pointed at a per-launch relocated config dir (`CODEX_HOME`) seeded with its credentials, leaving the real `~/.codex` entirely unwritten. The git common dir is granted as a **narrow allowlist** of only what `status/diff/add/commit/push/gc` write (`objects`, `refs`, `logs`, `packed-refs`, this worktree's gitdir, …) — never wholesale, so the repo `config`/`hooks`, the per-worktree gitdir redirection files, and **sibling worktree gitdirs** stay unwritable. Global toolchain bins (`~/.cargo/bin`, global `node_modules`, the npx cache, …) are never writable either.
-- **Environment**: each `srt` invocation runs under a sanitized env (`env -i` + a benign baseline). Unlike safehouse and sdx, the `srt` CLI inherits the host env, so without this an ambient `AWS_*`, `GITHUB_TOKEN`, etc. would reach the agent and bypass the read mask. Credentials the agent legitimately needs from the environment must be forwarded explicitly via the model's `preLaunchEnv` (the same opt-in pass-list safehouse uses).
+- **Environment**: each `srt` invocation runs under a sanitized env (`env -i` + a benign baseline). Unlike safehouse and sdx, the `srt` CLI inherits the host env, so without this an ambient `AWS_*`, `GITHUB_TOKEN`, etc. would reach the agent and bypass the read mask. Credentials the agent legitimately needs from the environment must be forwarded explicitly via the agent's `preLaunchEnv` (the same opt-in pass-list safehouse uses).
 - **Network**: allow-only, **reused from the same Clearance allowlist** (`CLEARANCE_ALLOW_HOSTS` / `CLEARANCE_ALLOW_HOSTS_FILES`, including the shipped `clearance-allow-hosts`) so there is one source of truth. Local binding and unix sockets stay off (never the Docker socket).
 
 ### Linux / WSL prerequisites
@@ -76,7 +76,7 @@ sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
 
 ## Docker Sandboxes Setup
 
-Each model that runs under `sdx` needs a `sandbox: { agent: "<sbx-agent>" }` block in `crew.config.ts`. Groundcrew addresses the sandbox as `groundcrew-<agent>` and reuses one existing sandbox per agent across repos and tasks.
+Each agent that runs under `sdx` needs a `sandbox: { agent: "<sbx-agent>" }` block in `crew.config.ts`. Groundcrew addresses the sandbox as `groundcrew-<agent>` and reuses one existing sandbox per agent across repos and tasks.
 
 First-time setup is manual:
 
@@ -86,4 +86,4 @@ sbx exec -it groundcrew-claude claude auth login
 sbx exec -it groundcrew-claude gh auth login
 ```
 
-Replace `claude` with the sbx agent for the model and `<projectDir>` with `workspace.projectDir` from `crew.config.ts`. Manage lifecycle and auth with `sbx` directly (`sbx ls`, `sbx exec`, `sbx rm`). Groundcrew does not create, authenticate, regenerate, list, or remove sandboxes.
+Replace `claude` with the sbx agent name for your agent and `<projectDir>` with `workspace.projectDir` from `crew.config.ts`. Manage lifecycle and auth with `sbx` directly (`sbx ls`, `sbx exec`, `sbx rm`). Groundcrew does not create, authenticate, regenerate, list, or remove sandboxes.

package/docs/task-sources.md

@@ -35,9 +35,15 @@ tasks only). If omitted, groundcrew treats in-review advancement as unsupported
 for that source and does not claim the transition succeeded. `commands.markDone`,
 when set, receives the same `sourceRef` and is run after groundcrew sees a
 **merged** PR on the task's worktree branch (a merged PR never advances to
-in-review). If omitted, groundcrew treats done advancement as unsupported and
-leaves the task for the source's own integration to close out. `${id}`,
-`${canonicalId}`, and `${name}` placeholders are shell-quoted before substitution.
+in-review), or when a human or worker runs `crew task done <task-id>` for
+completed no-PR work. If omitted, groundcrew treats done advancement as
+unsupported and leaves the task for the source's own integration to close out.
+`${id}`, `${canonicalId}`, and `${name}` placeholders are shell-quoted before substitution.
+
+Workers receive `GROUNDCREW_TASK_ID` and `GROUNDCREW_COMPLETE` in their launch
+environment. The default prompt tells them to run `GROUNDCREW_COMPLETE` only
+when the requested work is complete, no PR is needed, and any dirty worktree
+state is expected or explicitly allowed.
 
 ```json
 [
@@ -78,7 +84,7 @@ export default {
 };
 ```
 
-Creating a todo task appends a line with `status:todo` as the final meaningful token and writes the prompt to `.tasks/<id>.md`. New todo tasks default to priority `A`; pass `--priority <letter>` to override it. If `--agent` is omitted, the task uses `agent:any`.
+Creating a todo task appends a line with `status:todo` as the final meaningful token and writes the prompt to `.tasks/<id>.md`. Pass `--repo <repo>` unless the source configures `defaultRepository`. Pass `--priority <letter>` to add a todo.txt priority marker. If `--agent` is omitted, the task uses `agent:any`.
 
 ```bash
 crew task create "Fix cancellation retry race" \
@@ -91,7 +97,7 @@ crew task create "Fix cancellation retry race" \
 ```
 
 ```txt
-(A) Fix cancellation retry race +marketplace @backend id:GC-20260608-001 repo:ClipboardHealth/api agent:codex status:todo
+Fix cancellation retry race +marketplace @backend id:GC-20260608-001 repo:ClipboardHealth/api agent:codex status:todo
 ```
 
 For hand-written todo lines, a non-empty title is enough prompt text when `.tasks/<id>.md` is absent. Omit `agent:` to default to `agent:any`:

package/docs/troubleshooting.md

@@ -2,12 +2,12 @@
 
 First stop for "what exists locally right now": `crew status <task>` shows the task's worktrees, workspace presence, run state, logs, and task-source status. Use `crew doctor` when you need to verify host setup.
 
-## Missing Model CLI
+## Missing Agent CLI
 
-`crew doctor` probes every model listed in `models.definitions`. If you do not have `codex` installed, initialize with `crew init --model claude` or leave `codex` out of the enabled model set:
+`crew doctor` probes every agent listed in `agents.definitions`. If you do not have `codex` installed, initialize with `crew init --agent claude` or leave `codex` out of the enabled agent set:
 
 ```ts
-models: {
+agents: {
   default: "claude",
   definitions: {
     claude: {},
@@ -19,7 +19,7 @@ If `codex: {}` is listed, doctor expects the `codex` CLI to be installed because
 
 ## Safehouse-Wrapped Commands Are Not Re-Wrapped
 
-If a `models.definitions.<name>.cmd` already starts with `safehouse`, groundcrew assumes that command owns its Safehouse flags and does not add the `safehouse-clearance` wrapper a second time. Changing the proxy's allowlist after it is running requires killing the PID in `${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.pid` so the next launch picks up the new env.
+If a `agents.definitions.<name>.cmd` already starts with `safehouse`, groundcrew assumes that command owns its Safehouse flags and does not add the `safehouse-clearance` wrapper a second time. Changing the proxy's allowlist after it is running requires killing the PID in `${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.pid` so the next launch picks up the new env.
 
 ## Dead Tmux Windows Vanish By Default
 
@@ -31,13 +31,15 @@ This applies to the tmux backend only.
 
 Groundcrew marks a task `In Progress` when it provisions a workspace. When a PR opens on that worktree branch, the reviewer pass attempts to mark the task `In Review`. Linear's default `In Review` status works out of the box; if your team renamed it, configure `sources: [{ kind: "linear", statuses: { inReview: ["Code Review"] } }]`.
 
+If the task intentionally has no PR, mark it complete with `crew task done <task-id>`. Groundcrew refuses dirty matching worktrees with no PR unless you pass `--allow-dirty`, so inspect or commit/stash unexpected changes first. For todo-txt tasks with `rec:`, this completion path also lets the source schedule the next recurrence.
+
 ## Claude Launches In Auto Mode By Default
 
-Groundcrew creates isolated per-task worktrees for unattended runs, so the shipped `claude` command is `claude --permission-mode auto` to let Claude proceed without stopping for clarifying questions while keeping its built-in safety prompts intact. Override `models.definitions.claude.cmd` for `bypassPermissions` if you need to suppress tool-permission prompts entirely, or for a stricter mode.
+Groundcrew creates isolated per-task worktrees for unattended runs, so the shipped `claude` command is `claude --permission-mode auto` to let Claude proceed without stopping for clarifying questions while keeping its built-in safety prompts intact. Override `agents.definitions.claude.cmd` for `bypassPermissions` if you need to suppress tool-permission prompts entirely, or for a stricter mode.
 
 ## Doctor's Command Introspection Is Shallow
 
-Doctor reports the resolved local runner and whether its prerequisites are met, then tokenizes model `cmd` and checks the first two non-flag tokens against PATH. Boolean flags without values, env-var assignments (`FOO=1`), shell pipelines, and subshells are not parsed. When `local.runner` is `"none"`, doctor surfaces a single WARNING line.
+Doctor reports the resolved local runner and whether its prerequisites are met, then tokenizes agent `cmd` and checks the first two non-flag tokens against PATH. Boolean flags without values, env-var assignments (`FOO=1`), shell pipelines, and subshells are not parsed. When `local.runner` is `"none"`, doctor surfaces a single WARNING line.
 
 ## Switch To Tmux If Cmux Is Misbehaving
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.34.2",
+  "version": "4.35.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",
@@ -77,7 +77,7 @@
   },
   "devDependencies": {
     "@clipboard-health/ai-rules": "2.27.0",
-    "@clipboard-health/oxlint-config": "1.10.14",
+    "@clipboard-health/oxlint-config": "1.10.21",
     "@nx/js": "22.7.5",
     "@tsconfig/node24": "24.0.4",
     "@tsconfig/strictest": "2.0.8",