@crewx/sdk 0.9.0-rc.94 → 0.9.0-rc.96

package/dist/repository/task-status.d.ts

@@ -0,0 +1,14 @@
+export type TaskStatus = 'pending' | 'running' | 'paused' | 'success' | 'failed' | 'stopped' | 'runner_lost';
+export declare const TASK_TERMINAL_STATUSES: readonly ["success", "failed", "stopped", "runner_lost"];
+export type TaskTerminalStatus = (typeof TASK_TERMINAL_STATUSES)[number];
+export type TaskTerminalReason = 'user_stop' | 'runner_lost' | 'launch_failed';
+export declare const LEGACY_TASK_TERMINAL_ERROR_PATTERNS: {
+    readonly stopped: RegExp;
+    readonly runnerLost: RegExp;
+};
+export interface TaskStatusInput {
+    status: string;
+    error?: string | null;
+    metadata?: string | null;
+}
+export declare function normalizeTaskStatus(row: TaskStatusInput): TaskStatus;

package/dist/repository/task.repository.d.ts

@@ -1,8 +1,37 @@
 import { BaseSqliteRepository } from './base-sqlite-repository.js';
 import { tasks } from '../schema/index.js';
 import type { TaskLogEntry, TaskLogReadResult, TaskLogState } from './task-log.repository.js';
-export type TaskRow = typeof tasks.$inferSelect;
+import { type TaskStatus, type TaskTerminalReason } from './task-status.js';
+import { type StopTaskOptions, type StopTaskResult } from '../lifecycle/task-stop.js';
+export { TASK_HEARTBEAT_HARD_STALE_MS, TASK_HEARTBEAT_INTERVAL_MS, TASK_HEARTBEAT_STALE_MS, resolveTaskHeartbeatHardStaleMs, resolveTaskHeartbeatIntervalMs, resolveTaskHeartbeatStaleMs, } from '../lifecycle/task-heartbeat.js';
+type RawTaskRow = typeof tasks.$inferSelect;
+export type TaskRow = Omit<RawTaskRow, 'status'> & {
+    status: TaskStatus;
+};
 export type NewTask = typeof tasks.$inferInsert;
+export type TaskKillStatus = 'terminated' | 'not_found' | 'failed' | 'not_running';
+export interface TaskKillResult {
+    status: TaskKillStatus;
+    killed: boolean;
+    pid?: number;
+    error?: string;
+}
+export interface TaskStopRequestResult {
+    accepted: boolean;
+    status: string | null;
+    runEpoch: number;
+    alreadyRequestedAt?: string;
+}
+export type TaskStopMethod = 'cooperative' | 'forced';
+export interface FinalizeTaskStopOptions {
+    id: string;
+    runEpoch: number;
+    completedAt?: string;
+    method: TaskStopMethod;
+    error?: string;
+    terminalReason?: TaskTerminalReason;
+    durationMs?: number | null;
+}
 export type TaskListRow = Pick<TaskRow, 'id' | 'thread_id' | 'agent_id' | 'status' | 'parent_task_id' | 'started_at' | 'completed_at' | 'duration_ms' | 'input_tokens' | 'output_tokens' | 'cost_usd' | 'error'>;
 export type TaskActivityLogRow = Pick<TaskRow, 'id' | 'thread_id' | 'agent_id' | 'parent_task_id' | 'started_at' | 'completed_at'>;
 export type FindTasksByThreadOptions = {
@@ -36,6 +65,7 @@ export interface AgentUsageRow {
     agentId: string;
     workspaceId: string | null;
     totalTasks: number;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -45,6 +75,7 @@ export interface AgentUsageRow {
 export interface TrendRow {
     date: string;
     agentId: string;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -54,6 +85,7 @@ export interface TrendRow {
 export interface ProviderUsageRow {
     provider: string;
     totalTasks: number;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -66,6 +98,7 @@ export interface ModelUsageRow {
     model: string;
     provider: string;
     totalTasks: number;
+    unavailableTaskCount?: number;
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens: number;
@@ -107,17 +140,38 @@ export interface ThreadChain {
     targetAgentTurnCount: number;
     turns: ThreadChainTurn[];
 }
+type TaskUsageColumns = Pick<TaskRow, 'input_tokens' | 'output_tokens' | 'cached_input_tokens' | 'cost_usd'>;
+export declare function mergeTerminalReason(metadataJson: string | null | undefined, reason: TaskTerminalReason): string;
+export declare function hasRecordedUsage(task: TaskUsageColumns): boolean;
 export declare const PID_NULL_REAP_GRACE_MS: number;
+export declare const PENDING_ADOPT_GRACE_MS: number;
+export declare const DEFAULT_TASK_REAPER_TICK_INTERVAL_MS: number;
+export interface ReapOrphanedTasksOptions {
+    tickIntervalMs?: number;
+}
 export declare class TaskRepository extends BaseSqliteRepository {
     private readonly dbPath?;
+    private readonly clock;
     private readonly taskLogRepository;
+    private lastReaperTickAt?;
     private readonly pidNullObservedSince;
     constructor(opts?: {
         dbPath?: string;
         dbRoot?: string;
+        clock?: () => number;
     });
     resolveDbPath(): string;
     private openHandle;
+    heartbeatTask(opts: {
+        id: string;
+        runEpoch: number;
+    }): boolean;
+    requestTaskStop(opts: {
+        id: string;
+        requestedAt: string;
+    }): TaskStopRequestResult;
+    finalizeTaskStop(opts: FinalizeTaskStopOptions): boolean;
+    stopTask(id: string, options?: StopTaskOptions): Promise<StopTaskResult>;
     startTask(opts: {
         id: string;
         agentId: string;
@@ -140,6 +194,14 @@ export declare class TaskRepository extends BaseSqliteRepository {
         renderedPrompt?: string | null;
         codingAgentCommand?: string | null;
     }): void;
+    updateTaskOwnership(opts: {
+        id: string;
+        runEpoch: number;
+        ownership: 'runner' | 'caller';
+        providerPid?: number | null;
+    }): boolean;
+    adoptPendingTask(id: string): boolean;
+    failPendingTask(id: string, error: string, completedAt?: string): boolean;
     listTasksByProjectId(projectId: string): TaskRow[];
     finishTask(opts: {
         id: string;
@@ -159,11 +221,12 @@ export declare class TaskRepository extends BaseSqliteRepository {
     }): void;
     updateTaskLifecycle(opts: {
         id: string;
-        status: string;
+        status: TaskStatus;
         error: string | null;
         completedAt: string | null;
         durationMs: number | null;
         workspaceId: string;
+        terminalReason?: TaskTerminalReason;
     }): void;
     appendLog(taskId: string, entry: {
         timestamp: string;
@@ -175,13 +238,11 @@ export declare class TaskRepository extends BaseSqliteRepository {
     readLogsTail(taskId: string, limit: number): TaskLogReadResult | undefined;
     getLogState(taskId: string): TaskLogState | undefined;
     getRunningTasks(): TaskRow[];
+    getActiveTasks(): TaskRow[];
     getAllTasks(): TaskRow[];
     getTask(id: string): TaskRow | undefined;
-    killTask(id: string): {
-        killed: boolean;
-        pid?: number;
-    };
-    reapOrphanedTasks(): number;
+    killTask(id: string): Promise<TaskKillResult>;
+    reapOrphanedTasks(options?: ReapOrphanedTasksOptions): number;
     reapRunningWorkflowTasks(graceMs?: number): number;
     findTaskStatus(taskId: string, workspaceId?: string): TaskRow | undefined;
     findChildTasks(parentTaskId: string, workspaceId?: string): TaskRow[];
@@ -239,7 +300,7 @@ export declare class TaskRepository extends BaseSqliteRepository {
         completed_at: string | null;
         metadata: string | null;
     } | null;
-    markTaskFailed(taskId: string, error: string, workspaceId?: string): void;
+    markTaskFailed(taskId: string, error: string, workspaceId?: string, status?: TaskStatus, terminalReason?: TaskTerminalReason): void;
     findTasksByPromptHint(hint: string, workspaceId?: string): TaskRow[];
     getProviderUsage(from: string, to: string, workspace?: string): ProviderUsageRow[];
     getModelUsage(from: string, to: string, workspace?: string): ModelUsageRow[];

package/dist/repository/usage-backfill.d.ts

@@ -0,0 +1,62 @@
+export type UsageBackfillMode = 'dry-run' | 'apply' | 'verify' | 'restore';
+export declare const USAGE_BACKFILL_TERMINAL_STATUSES: readonly ["success", "failed", "completed"];
+export declare const USAGE_BACKFILL_MAX_LATE_USAGE_AGE_MS: number;
+export declare const USAGE_BACKFILL_UNDO_SCHEMA_VERSION = 1;
+export declare const USAGE_BACKFILL_SNAPSHOT_ROW_BYTES = 2048;
+export declare const USAGE_BACKFILL_MIN_FREE_SPACE_RESERVE_BYTES: number;
+export type UsageAccountingReason = 'pre-instrumentation' | 'provider-no-usage' | 'suppressed-by-adapter' | 'not-captured';
+export interface UsageBackfillOptions {
+    mode: UsageBackfillMode;
+    dbPath?: string;
+    backupPath?: string;
+    restorePath?: string;
+    now?: Date | string | number;
+}
+export interface UsageBackfillProviderStats {
+    candidates: number;
+    recovered: number;
+    unavailable: number;
+    deferred: number;
+}
+export interface UsageBackfillFailure {
+    taskId: string;
+    reason: string;
+}
+export interface UsageBackfillReport {
+    mode: UsageBackfillMode;
+    ok: boolean;
+    dbPath: string;
+    scannedTasks: number;
+    terminalTasks: number;
+    rawTargetTasks: number;
+    candidateTasks: number;
+    recoveredTasks: number;
+    unavailableTasks: number;
+    deferredTasks: number;
+    changedTasks: number;
+    wouldChangeTasks: number;
+    accountingTasks: number;
+    remainingTargetTasks: number;
+    providerDistribution: Record<string, UsageBackfillProviderStats>;
+    reasonCounts: Record<UsageAccountingReason, number>;
+    estimatedFreeSpaceBytes: number;
+    requiredFreeSpaceBytes: number;
+    availableFreeSpaceBytes: number;
+    minimumFreeSpaceReserveBytes: number;
+    freeSpaceGatePassed: boolean;
+    backupPath?: string;
+    snapshotPath?: string;
+    backupMethod?: 'row-undo-snapshot';
+    restored: number;
+    skippedConflict: number;
+    conflictSamples: UsageBackfillConflict[];
+    blockedReason?: string;
+    failures: UsageBackfillFailure[];
+    warnings: string[];
+}
+export interface UsageBackfillConflict {
+    taskId: string;
+    fields: string[];
+}
+export declare function classifyUsageAccountingReason(provider: string | undefined): UsageAccountingReason;
+export declare function runUsageBackfill(options: UsageBackfillOptions): Promise<UsageBackfillReport>;

package/dist/repository/usage-from-logs.d.ts

@@ -0,0 +1,21 @@
+import type { CliProviderAdapter } from '../provider/cli/adapter.types.js';
+import type { TaskLogRepositoryContract } from './task-log.repository.js';
+export interface RecoveredTaskUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    costUsd: number;
+    model: string | null;
+}
+export interface TaskLogUsageRecovery {
+    stdout: string;
+    adapter: CliProviderAdapter;
+    usage?: RecoveredTaskUsage;
+}
+export interface RecoverUsageFromTaskLogsOptions {
+    taskLogRepository: Pick<TaskLogRepositoryContract, 'readLogs'>;
+    taskId: string;
+    provider?: string | null;
+    model?: string | null;
+}
+export declare function recoverUsageFromTaskLogs(options: RecoverUsageFromTaskLogsOptions): TaskLogUsageRecovery | undefined;

package/dist/schema/tasks.d.ts

@@ -429,6 +429,61 @@ export declare const tasks: import("drizzle-orm/sqlite-core").SQLiteTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        heartbeat_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "heartbeat_at";
+            tableName: "tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        stop_requested_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "stop_requested_at";
+            tableName: "tasks";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        stop_requested_epoch: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "stop_requested_epoch";
+            tableName: "tasks";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         rendered_prompt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "rendered_prompt";
             tableName: "tasks";

package/dist/schema/ui-instances.d.ts

@@ -114,6 +114,25 @@ export declare const ui_instances: import("drizzle-orm/sqlite-core").SQLiteTable
         }, {}, {
             length: number | undefined;
         }>;
+        app_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "app_id";
+            tableName: "ui_instances";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
         anchor_task_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "anchor_task_id";
             tableName: "ui_instances";

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 import type { Platform } from '../conversation/types';
+import type { McpAppStateDescriptor } from '../mcp-app/types';
 import { z } from 'zod';
 export declare const AgentInlineSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
@@ -740,14 +741,14 @@ export declare const WiBoardSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     goal_id: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
     name: string;
+    id: string;
     workflow_id: string;
     description?: string | undefined;
     goal_id?: string | undefined;
 }, {
-    id: string;
     name: string;
+    id: string;
     workflow_id: string;
     description?: string | undefined;
     goal_id?: string | undefined;
@@ -2840,6 +2841,7 @@ export interface QueryOptions {
     platform?: Platform;
     messages?: import('../conversation/types').TemplateMessage[];
     uiProjections?: readonly import('../ui-instance/types').UiAgentContextProjection[];
+    mcpAppProjections?: readonly McpAppStateDescriptor[];
     vars?: Record<string, unknown>;
     cwd?: string;
     resumeSessionId?: string;
@@ -2886,6 +2888,7 @@ export interface ExecuteOptions {
     platform?: Platform;
     messages?: import('../conversation/types').TemplateMessage[];
     uiProjections?: readonly import('../ui-instance/types').UiAgentContextProjection[];
+    mcpAppProjections?: readonly McpAppStateDescriptor[];
     vars?: Record<string, unknown>;
     cwd?: string;
     resumeSessionId?: string;

package/dist/ui-instance/index.d.ts

@@ -1,7 +1,8 @@
-export type { ActionReceipt, ActionReceiptOutcome, CreateUiInstanceInput, JsonObject, JsonPrimitive, JsonValue, UiActionHandlerContext, UiActionHandlerRegistration, UiActionHandlerResult, UiActionEnvelope, UiActor, UiDefinition, UiDefinitionAction, UiDefinitionInput, UiDefinitionRef, UiProjectionPolicy, UiExecutionContext, UiAuthenticatedActor, UiAuthenticatedExecutionContext, UiAuthenticatedGrantPolicy, UiServerRuntimeFacade, UiServerRuntimeOptions, UiAgentContextProjection, UiExternalActionHandlerRegistration, UiInstance, UiInstanceStatus, UiLocalGrantPolicy, UiRuntimeFacade, UiRuntimeOptions, UiStateActionHandlerRegistration, } from './types.js';
+export type { ActionReceipt, ActionReceiptOutcome, CreateUiInstanceInput, JsonObject, JsonPrimitive, JsonValue, UiActionHandlerContext, UiActionHandlerRegistration, UiActionHandlerResult, UiActionEnvelope, UiActionConfirmation, UiActor, UiDefinition, UiDefinitionAction, UiDefinitionInput, UiDefinitionRef, UiProjectionPolicy, UiExecutionContext, UiAuthenticatedActor, UiAuthenticatedExecutionContext, UiAuthenticatedGrantPolicy, UiServerRuntimeFacade, UiServerRuntimeOptions, UiAgentContextProjection, UiExternalActionHandlerRegistration, UiInstance, UiInstanceStatus, UiLocalGrantPolicy, UiRuntimeFacade, UiRuntimeOptions, UiStateActionHandlerRegistration, } from './types.js';
 export { resolveUiEffectiveCapabilities } from './types.js';
 export { UiRuntimeError } from './errors.js';
 export type { UiRuntimeErrorCode } from './errors.js';
+export { projectSafeJsonObject } from './json.js';
 export { hashUiDefinition } from './definition.js';
 export { UiInstanceStore, openUiInstanceReadStore } from './store.js';
 export type { UiAuditSnapshotInput, UiInstanceReadStore } from './store.js';

package/dist/ui-instance/store.d.ts

@@ -8,7 +8,7 @@ export interface ReservationInput {
     requestId: string;
     actionId: string;
     actor: UiActor;
-    source: 'cli' | 'ui_host' | 'system';
+    source: 'cli' | 'ui_host' | 'system' | 'mcp';
     expectedRevision: number;
     input: JsonObject;
     now: number;
@@ -38,6 +38,7 @@ export interface UiAuditSnapshotInput {
 }
 export interface UiInstanceReadStore {
     get(instanceId: string): UiInstance | null;
+    listByThread(workspaceId: string, threadId: string): UiInstance[];
     close(): void;
 }
 export declare function openUiInstanceReadStore(dbPath?: string): UiInstanceReadStore;
@@ -54,6 +55,7 @@ export declare class UiInstanceStore {
         definitionHash: string;
         workspaceId: string;
         threadId: string;
+        appId?: string | null;
         anchorTaskId: string | null;
         domainRef: JsonObject;
         state: JsonObject;
@@ -61,6 +63,21 @@ export declare class UiInstanceStore {
         now: number;
     }): UiInstance;
     get(instanceId: string): UiInstance | null;
+    open(input: {
+        id?: string;
+        appId: string;
+        definitionId: string;
+        definitionVersion: number;
+        definitionHash: string;
+        workspaceId: string;
+        threadId: string;
+        anchorTaskId?: string | null;
+        domainRef: JsonObject;
+        state: JsonObject;
+        grants: readonly string[];
+        now: number;
+    }): UiInstance;
+    listByThread(workspaceId: string, threadId: string): UiInstance[];
     updateAuditSnapshot(input: UiAuditSnapshotInput): UiInstance | null;
     getReceipt(instanceId: string, requestId: string): ActionReceipt | null;
     runStateOnly(reservation: ReservationInput, handler: StateHandlerExecution['handle']): ActionReceipt;
@@ -73,6 +90,8 @@ export declare class UiInstanceStore {
         state: JsonObject;
         result: JsonObject | null;
         errorCode: string | null;
+        apply?: () => ReturnType<StateHandlerExecution['handle']>;
+        restoreRevisionOnFailure?: boolean;
         now: number;
     }): ActionReceipt;
 }

package/dist/ui-instance/types.d.ts

@@ -9,9 +9,11 @@ export interface UiDefinitionRef {
     version: number;
     hash: string;
 }
+export type UiActionConfirmation = 'none' | 'native';
 export interface UiDefinitionAction {
     readonly capabilities: readonly string[];
     readonly inputKeys?: readonly string[];
+    readonly confirmation?: UiActionConfirmation;
     readonly resultProjection?: UiProjectionPolicy;
 }
 export interface UiProjectionPolicy {
@@ -41,6 +43,7 @@ export interface UiInstance {
     definition: UiDefinitionRef;
     workspaceId: string;
     threadId: string;
+    appId: string | null;
     anchorTaskId: string | null;
     domainRef: JsonObject;
     state: JsonObject;
@@ -63,9 +66,12 @@ export type UiActor = {
 } | {
     kind: 'authenticated';
     id: string;
+} | {
+    kind: 'agent';
+    id: string;
 };
 export interface UiExecutionContext {
-    source: 'cli' | 'ui_host' | 'system';
+    source: 'cli' | 'ui_host' | 'system' | 'mcp';
     workspaceId: string;
     actor: UiActor;
 }
@@ -86,7 +92,7 @@ export interface ActionReceipt {
     requestId: string;
     actionId: string;
     actor: UiActor;
-    source: 'cli' | 'ui_host' | 'system';
+    source: 'cli' | 'ui_host' | 'system' | 'mcp';
     expectedRevision: number;
     beforeRevision: number;
     afterRevision: number | null;
@@ -114,7 +120,7 @@ export interface UiLocalGrantPolicy {
 export interface UiActionHandlerContext {
     instance: UiInstance;
     actor: UiActor;
-    source: 'cli' | 'ui_host' | 'system';
+    source: 'cli' | 'ui_host' | 'system' | 'mcp';
     input: JsonObject;
     requestId: string;
 }

package/dist/utils/runner-env.d.ts

@@ -0,0 +1,3 @@
+export declare const CREWX_RUNNER_IDENTITY_ENV: readonly ["CREWX_ASSIGNED_TASK_ID", "CREWX_DETACHED_RUNNER"];
+export declare function withoutCrewxRunnerIdentity(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function withoutCrewxRootContext(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/sdk",
-  "version": "0.9.0-rc.94",
+  "version": "0.9.0-rc.96",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=20.19.0"
@@ -55,6 +55,11 @@
       "import": "./dist/desktop/index.js",
       "require": "./dist/desktop/index.js"
     },
+    "./process": {
+      "types": "./dist/process/index.d.ts",
+      "import": "./dist/process/index.js",
+      "require": "./dist/process/index.js"
+    },
     "./publish": {
       "types": "./dist/publish/index.d.ts",
       "import": "./dist/publish/index.js",
@@ -78,6 +83,8 @@
     "./dist/esm/repository/index.js": false,
     "./dist/desktop/index.js": false,
     "./dist/esm/desktop/index.js": false,
+    "./dist/process/index.js": false,
+    "./dist/esm/process/index.js": false,
     "./dist/publish/index.js": false,
     "./dist/esm/publish/index.js": false,
     "./dist/account/index.js": false,

package/templates/agents/default.yaml

@@ -140,16 +140,22 @@ layouts:
             when it completes" are NOT true in this mode. That notification will never
             arrive; trusting it silently kills the delegated work.
 
-          Rules for delegation and long-running commands:
-          - Run delegations (crewx q / crewx x) in the FOREGROUND and wait for
-            the result within the same turn. Never use run_in_background, `&`, or nohup
-            for a CrewX delegation.
-          - If the harness force-moves a long command to the background (e.g. on
-            timeout), do NOT end your turn. Keep checking completion with short
-            foreground status checks until it actually finishes.
-          - A PID, a "running" status, a partially created file, or a --thread link is
-            NOT evidence of completion. Report success only after the command has
-            exited and returned its final result.
+          Delegation procedure:
+          1. Inside an agent process, `crewx q` and `crewx x` immediately return a
+             receipt (task ID). A receipt means accepted, not completed.
+          2. Recover the result by calling `crewx result <id>` with the next wait value
+             printed in the command's action guidance. That value increases automatically
+             as the task runs longer. Exit 124 means the work is still in progress, so
+             follow the next action guidance again. Read the terminal status before
+             judging the outcome.
+          3. Do not use `&`, `nohup`, or another background execution method. The
+             runner owns the work, so it continues after your turn ends.
+          4. Add `--wait` when a short call should run synchronously and is expected
+             to finish within the harness time limit.
+          5. Accepted does not mean successful. Read both the status and body from
+             `crewx result` before reporting completion.
+          6. The harness warning that background commands may be killed still
+             applies to commands it owns; this runner is outside that process tree.
         </delegation_lifecycle>
         </agent_profile>
         {{/if}}