@skrr-ai/cli 0.1.109 → 0.1.111

package/dist/lib/preflight-copy.js

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sourceRefusalWords = sourceRefusalWords;
 exports.gateExplanationLines = gateExplanationLines;
+exports.placementTargetLines = placementTargetLines;
 exports.capabilityStatusLabel = capabilityStatusLabel;
 /** What a refused event-source code means, in words. An unknown code is printed as it is. */
 const SOURCE_REFUSAL_WORDS = {
@@ -74,6 +75,36 @@ function gateExplanationLines(gate) {
     }
     return [];
 }
+function placementTargetWords(target) {
+    if (target.reachable === false)
+        return 'the chain never reaches it';
+    if (target.consent?.granted === false) {
+        return `consent refused${target.consent.reason ? ` (${target.consent.reason})` : ''}`;
+    }
+    if (target.contract?.verdict === 'unknown')
+        return 'contract support could not be read';
+    if (target.contract?.verdict && target.contract.verdict !== 'pass') {
+        return `cannot enforce the contract${target.contract.reason ? ` (${target.contract.reason})` : ''}`;
+    }
+    return target.usable ? 'could take the run' : 'unknown';
+}
+/**
+ * One line per execution target under "Is there somewhere else it can run?" (OSK-17003): the
+ * product, consent, contract and reachability the resolver would apply. The gate used to report a
+ * bare `fallbackCandidates` count, which read the same for a fallback that could take the run and
+ * one that never could. Nothing is printed for a single primary — the gate's note says that.
+ */
+function placementTargetLines(gate) {
+    if (gate.id !== 'placement')
+        return [];
+    const targets = Array.isArray(gate.detail?.targets)
+        ? gate.detail.targets
+        : [];
+    if (targets.length < 2)
+        return [];
+    return targets.map((target) => `#${target.index ?? '?'} ${target.role ?? 'target'} ${target.product ?? 'unknown'}` +
+        `${target.selector ? ` (${target.selector})` : ''}: ${placementTargetWords(target)}`);
+}
 /**
  * The status word for a capability. A credential whose expiry has passed is `expired`, not the
  * storage word `stale`, which gave no sign that time had run out.

package/dist/lib/profile-machine-identity-guard.js

@@ -32,9 +32,19 @@ function legacyProfileSharesDefaultMachine() {
  */
 function describeLegacySharedProfile(profile) {
     const next = `${profile}-2`;
+    // WHY this profile is on the shared row, from the record that decided it: which
+    // file made it "already hold credentials", and when. Absent rather than guessed
+    // when the record cannot be read.
+    let why = '';
+    try {
+        why = `${(0, machine_uuid_1.describeMachineIdentity)().sentence} `;
+    }
+    catch {
+        why = '';
+    }
     return [
         `Profile '${profile}' was set up by an older ${data_provider_1.BRAND.displayName} version that gave every profile on this ` +
-            'computer the same machine identity, and it still has it. Signing in here would replace the default ' +
+            `computer the same machine identity, and it still has it. ${why}Signing in here would replace the default ` +
             "profile's device-key pin and sign the default daemon out. Nothing was changed.",
         `Use a new profile name instead: skrr login --profile ${next}`,
         `(For the background service alone: skrrd --profile ${next} login)`,

package/dist/lib/roles.d.ts

@@ -105,7 +105,7 @@ export declare const roleApi: {
                     } | undefined;
                     escalation?: {
                         minimumSeverity?: "low" | "medium" | "high" | undefined;
-                        channel?: "push" | "none" | "email" | "cli" | "app" | "slack" | undefined;
+                        channel?: "push" | "none" | "cli" | "app" | "email" | "slack" | undefined;
                     } | undefined;
                     noReply?: {
                         enabled?: boolean | undefined;
@@ -182,7 +182,7 @@ export declare const roleApi: {
                 } | undefined;
                 escalation?: {
                     minimumSeverity?: "low" | "medium" | "high" | undefined;
-                    channel?: "push" | "none" | "email" | "cli" | "app" | "slack" | undefined;
+                    channel?: "push" | "none" | "cli" | "app" | "email" | "slack" | undefined;
                 } | undefined;
                 noReply?: {
                     enabled?: boolean | undefined;

package/dist/lib/task-admission.d.ts

@@ -0,0 +1,9 @@
+/** The server owns admission; this is a display projection, never a permission grant. */
+import type { TaskExecutionAdmission } from '@skrr-ai/data-provider';
+export type { TaskExecutionAdmission } from '@skrr-ai/data-provider';
+export declare function admissionLines(value: TaskExecutionAdmission | null | undefined): string[];
+export declare function isAdmissionPreview(value: unknown): value is {
+    dryRun: true;
+    taskId: string;
+    executionAdmission: TaskExecutionAdmission;
+};

package/dist/lib/task-admission.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.admissionLines = admissionLines;
+exports.isAdmissionPreview = isAdmissionPreview;
+function admissionLines(value) {
+    if (!value)
+        return ['Execution admission: not reported by this server.'];
+    const lines = [`Approval prerequisites: ${value.state}.`];
+    if (value.permission) {
+        lines.push(`Permission policy: ${value.permission.mode || 'inherited/unknown'} (${value.permission.source || 'source unavailable'}).`);
+    }
+    if (value.workingDirectory) {
+        lines.push(`Working directory: ${value.workingDirectory.path || 'daemon configured default'} (${value.workingDirectory.source}; existence and access are checked on the machine at start).`);
+    }
+    if (value.unattended && !value.approverAvailable) {
+        lines.push('This run is unattended. Tools that need approval cannot obtain it during the run.');
+    }
+    for (const constraint of value.constraints || []) {
+        if (constraint.message)
+            lines.push(constraint.message);
+        if (constraint.requiredAction)
+            lines.push(`Action: ${constraint.requiredAction}`);
+    }
+    lines.push('This checks execution prerequisites; task authorization and tool permissions still apply.');
+    return lines;
+}
+function isAdmissionPreview(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    const admission = row.executionAdmission;
+    return row.dryRun === true && typeof row.taskId === 'string' && Boolean(admission &&
+        ['ready', 'blocked', 'unknown'].includes(String(admission.state)) &&
+        admission.scope === 'approval_prerequisites');
+}

package/dist/lib/task-batch.d.ts

@@ -72,6 +72,8 @@ export type BatchProgress = {
     total: number;
     round: number;
     elapsedMs: number;
+    /** Submitted writes whose outcomes are still unknown after reconciliation. */
+    unknownKeys?: string[];
     /** Set while waiting before the next attempt, with why. */
     waiting?: {
         ms: number;
@@ -79,6 +81,8 @@ export type BatchProgress = {
     };
 };
 export type BatchCreateOptions = {
+    /** Called immediately before submitting a request; submitted writes may outlive the client. */
+    onSubmit?: (nodes: BatchCreateNode[]) => void;
     onProgress?: (progress: BatchProgress) => void;
 };
 /**

package/dist/lib/task-batch.js

@@ -206,6 +206,7 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
         total: nodes.length,
         round,
         elapsedMs: Date.now() - startedAt,
+        unknownKeys: [...unknown],
         ...(waiting ? { waiting } : {}),
     });
     /** Everything still owed becomes a failure that says whether it may exist. */
@@ -314,6 +315,7 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
         let waitReason = 'the server confirmed nothing';
         let response;
         try {
+            options.onSubmit?.(sent);
             response = await data_provider_1.dataService.createTasksBatch(items, {
                 idempotencyKey: batchIdempotencyKey('create', items),
             });

package/dist/lib/task-economics.d.ts

@@ -29,6 +29,16 @@ export declare function describeEstimate(economics: unknown): string;
  * scored and sorts after every row that is.
  */
 export declare function economicsScoreText(economics: unknown): string;
+/** A rank's score as the table prints it: rounded, or `—` when the row is not scored. */
+export declare function scoreText(score: number | null | undefined): string;
+/**
+ * What `tasks update` should say about the estimate, read from the server's `economicsChange`
+ * (OSK-16476): `null` means the write changed nothing (an identical re-send, or a retraction of
+ * an estimate that is not there). `undefined` (an older server, or no estimate in the request) says
+ * nothing, so the CLI never guesses. When the estimate was the whole request the caller prints this
+ * line INSTEAD of "Updated task"; otherwise it follows it.
+ */
+export declare function estimateUnchangedLine(sent: unknown, updated: Record<string, unknown> | undefined): string | null;
 /**
  * One line for a `task.economics.*` Activity event (OSK-15365): the revision, the claim after the
  * change and the claim it replaced, so `tasks activity` shows from-what-to-what without `--json`.

package/dist/lib/task-economics.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.economicsFromFlags = economicsFromFlags;
 exports.describeEstimate = describeEstimate;
 exports.economicsScoreText = economicsScoreText;
+exports.scoreText = scoreText;
+exports.estimateUnchangedLine = estimateUnchangedLine;
 exports.describeEconomicsChange = describeEconomicsChange;
 const data_provider_1 = require("@skrr-ai/data-provider");
 /**
@@ -83,8 +85,28 @@ function describeEstimate(economics) {
  * scored and sorts after every row that is.
  */
 function economicsScoreText(economics) {
-    const score = (0, data_provider_1.proposalEconomicsRank)(economics).score;
-    return score === null || !Number.isFinite(score) ? '—' : String(Math.round(score));
+    return scoreText((0, data_provider_1.proposalEconomicsRank)(economics).score);
+}
+/** A rank's score as the table prints it: rounded, or `—` when the row is not scored. */
+function scoreText(score) {
+    return score === null || score === undefined || !Number.isFinite(score)
+        ? '—'
+        : String(Math.round(score));
+}
+/**
+ * What `tasks update` should say about the estimate, read from the server's `economicsChange`
+ * (OSK-16476): `null` means the write changed nothing (an identical re-send, or a retraction of
+ * an estimate that is not there). `undefined` (an older server, or no estimate in the request) says
+ * nothing, so the CLI never guesses. When the estimate was the whole request the caller prints this
+ * line INSTEAD of "Updated task"; otherwise it follows it.
+ */
+function estimateUnchangedLine(sent, updated) {
+    if (sent === undefined || !updated || updated.economicsChange !== null)
+        return null;
+    if (sent === null)
+        return 'No estimate to retract; nothing changed.';
+    const revision = updated.economics?.revision;
+    return `Estimate unchanged${revision ? ` (revision ${revision})` : ''}: it already reads ${describeEstimate(updated.economics)}.`;
 }
 /**
  * One line for a `task.economics.*` Activity event (OSK-15365): the revision, the claim after the

package/dist/lib/task-operations.d.ts

@@ -0,0 +1,25 @@
+/** Documentation and display paths only. The server still owns allowedActions. */
+export declare function taskActionCommand(action: string, taskId: string, targetId: string | undefined, bin?: string, context?: {
+    allowedActions?: ReadonlyArray<{
+        action: string;
+    }>;
+}): string | undefined;
+export declare function taskOperationsGuide(bin?: string): {
+    title: string;
+    sections: ({
+        title: string;
+        commands: {
+            command: string;
+            purpose: string;
+        }[];
+        note?: undefined;
+    } | {
+        title: string;
+        note: string;
+        commands: {
+            command: string;
+            purpose: string;
+        }[];
+    })[];
+};
+export declare function taskOperationsGuideLines(bin?: string): string[];

package/dist/lib/task-operations.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskActionCommand = taskActionCommand;
+exports.taskOperationsGuide = taskOperationsGuide;
+exports.taskOperationsGuideLines = taskOperationsGuideLines;
+const shell_quote_1 = require("./shell-quote");
+/** Documentation and display paths only. The server still owns allowedActions. */
+function taskActionCommand(action, taskId, targetId, bin = 'skrr', context = {}) {
+    const task = (0, shell_quote_1.shellQuoteArg)(taskId);
+    const target = targetId ? (0, shell_quote_1.shellQuoteArg)(targetId) : '<id>';
+    const commands = {
+        answer_human_input: `tasks input answer ${task} --request ${target} --text <answer>`,
+        assign_task: `tasks assign ${task} --help`,
+        // Managed work already has a current Result. Its server-declared
+        // continuation surface distinguishes closing from submitting a new Result.
+        complete_task: context.allowedActions?.some(item => item.action === 'continue_task')
+            ? `tasks move ${task} --status done`
+            : `tasks complete ${task}`,
+        continue_task: `tasks continue ${task} --text "<instruction>" --command-key <key>`,
+        dismiss_human_input: `tasks input dismiss ${task} --request ${target}`,
+        inspect_dependency: `tasks show ${target} --json`,
+        interrupt_task: `tasks interrupt ${task}`,
+        request_approval: `tasks approvals create ${task} --type <review|sign_off|deployment>`,
+        resolve_approval: `tasks approvals resolve ${task} ${target} --status <approved|rejected>`,
+        resolve_task_hold: `tasks move ${task} --status <status>`,
+        retry_task: `tasks retry ${task}`,
+        set_execution_mode: `tasks update ${task} --execution-mode <agent|human>`,
+        start_task: `tasks start ${task}`,
+        triage_task: `tasks triage ${task}`,
+        unschedule_task: `tasks unschedule ${task}`,
+    };
+    return commands[action] ? `${bin} ${commands[action]}` : undefined;
+}
+function taskOperationsGuide(bin = 'skrr') {
+    const command = (usage, purpose) => ({ command: `${bin} ${usage}`, purpose });
+    return {
+        title: 'Task operations',
+        sections: [
+            {
+                title: 'Inspect and plan',
+                commands: [
+                    command('tasks show <task> --json', 'Read the Task, assignment, and dependency IDs.'),
+                    command('tasks actionability <task>', 'Read the canonical next actor, blocker, and allowed actions.'),
+                    command('tasks preflight <task>', 'Read workflow actionability and execution prerequisites together; creates no Run.'),
+                    command('tasks ready --for agent --agent <agent-id>', 'Find workflow-actionable work for an Agent; this does not verify its runtime.'),
+                    command('tasks create-tree --help', 'Create a related Task tree; blockedByTempIds declares dependencies within that tree.'),
+                ],
+            },
+            {
+                title: 'Choose assignment',
+                note: 'Executor intent, assignment, and starting a Run are separate choices. --unassigned clears both assignee kinds and suppresses automatic defaults; it does not start work.',
+                commands: [
+                    command('tasks create --title "Task title" --execution-mode agent --unassigned --dry-run --json', 'Preview Agent-intended work without selecting an Agent or writing a Task.'),
+                    command('tasks assign <task> --unassigned', 'Clear current assignees while retaining executor intent; creates no Run.'),
+                    command('tasks assign <task> --help', 'Choose an eligible Human or Agent explicitly using the native assignment options.'),
+                ],
+            },
+            {
+                title: 'Apply and recover a batch',
+                note: 'Keep the same JSON, scope, and external-key options after an incomplete result. Explicit node externalKey values are preserved; otherwise keys derive from the file and defaults. Changing that input can name new Tasks.',
+                commands: [
+                    command('tasks create-tree --from-json tasks.json --unassigned --readback --json', 'Apply the batch and reread its declared structured fields. This does not start Tasks.'),
+                    command('tasks create-tree --from-json tasks.json --unassigned --resume --readback --json', 'Continue the unchanged file: confirm existing IDs without patching them, create only missing nodes, then read back.'),
+                    command('tasks create-tree --from-json tasks.json --unassigned --verify-spec --json', 'Read-only structured-field comparison. Rich text and unsupported fields are explicitly unchecked; no Expectation assessment or drift repair is performed.'),
+                    command('tasks create-tree --from-json tasks.json --verify --json', 'Read-only existence check by external key. This makes no specification-equality claim.'),
+                ],
+            },
+            {
+                title: 'Name a Project or Goal',
+                note: 'Use exact scoped Project/Goal titles, native refs, or canonical IDs. Duplicate names refuse instead of choosing one. A qualified Project supplies containment; a qualified Goal changes the Goal relationship without moving the Task. Project external keys remain exact and case-sensitive, including keys containing slashes.',
+                commands: [
+                    command('tasks create --title "Task title" --space <space-id> --project "Exact project title" --goal "Exact Goal title" --unassigned --dry-run --json', 'Preview exact names inside the selected Space.'),
+                    command('tasks create --title "Task title" --project "<space-ref>/<project-ref-or-exact-title>" --goal "<space-ref>/<Goal-exact-title>" --unassigned --dry-run --json', 'Preview qualified references; native relationship permissions still apply.'),
+                    command('tasks create --title "Task title" --space <space-id> --project "<project-external-key>" --unassigned --dry-run --json', 'Reuse an existing Project’s native external key without rewriting it.'),
+                ],
+            },
+            {
+                title: 'Edit dependencies',
+                note: 'A waits for B: update A with --add-blocked-by B. These commands change dependencies; inspecting a blocker does not remove it.',
+                commands: [
+                    command('tasks update <task-A> --add-blocked-by <task-B>', 'Make A wait for B.'),
+                    command('tasks update <task-A> --remove-blocked-by <task-B>', 'Remove that dependency when the relationship is no longer intended.'),
+                    command('tasks update <task-B> --add-blocks <task-A>', 'The same relationship, edited from B.'),
+                ],
+            },
+            {
+                title: 'Check execution before starting',
+                note: 'Preflight reads server projections at separate times. It runs no shell command and cannot prove machine directory access, tool availability, or future approval. Starting rechecks current authority.',
+                commands: [
+                    command('tasks start <task> --dry-run --json', 'Read only the server-owned execution preview through the dedicated preview endpoint.'),
+                    command('agents show <agent-id>', 'Inspect the assigned Agent and its configured runtime.'),
+                    command('harnesses show <harness-id> --json', 'Inspect the actual Harness record and reported provider credential readiness, where available.'),
+                    command('harnesses installers --daemon <daemon-id>', 'Ask that daemon about installed coding CLIs and sign-in where it can tell; this is not a shell execution test.'),
+                    command('harnesses ping <harness-id>', 'Explicitly probe a local daemon for reachability; an answer does not prove a provider can run a task.'),
+                    command('tasks start <task>', 'Start a new Run after reviewing the checks. This command executes work.'),
+                ],
+            },
+            {
+                title: 'Follow and finish',
+                commands: [
+                    command('tasks show <task>', 'Inspect current execution and follow the Task link.'),
+                    command('tasks expectations <task>', 'Read what is owed and how it will be checked.'),
+                    command('tasks result submit <task> --help', 'Submit the concrete result and evidence.'),
+                    command('tasks review <task> --help', 'Review another actor’s exact Result.'),
+                    command('tasks complete <task> --help', 'Submit a Result and close out when appropriate.'),
+                    command('instructions guide task-management', 'Read the detailed canonical workflow guide; --offline uses the bundled release copy.'),
+                ],
+            },
+        ],
+    };
+}
+function taskOperationsGuideLines(bin = 'skrr') {
+    const guide = taskOperationsGuide(bin);
+    const lines = [guide.title];
+    for (const section of guide.sections) {
+        lines.push('', section.title);
+        if (section.note)
+            lines.push(section.note);
+        for (const entry of section.commands)
+            lines.push(`  ${entry.command}\n    ${entry.purpose}`);
+    }
+    return lines;
+}

package/dist/lib/task-preflight.d.ts

@@ -0,0 +1,35 @@
+import type { TaskActionabilityResponse } from '@skrr-ai/data-provider';
+type AdmissionPreview = {
+    dryRun: true;
+    taskId: string;
+    taskSpecVersion?: number | null;
+    taskRevision?: number | null;
+    executionAdmission: import('./task-admission').TaskExecutionAdmission;
+};
+type Observation<T> = {
+    status: 'observed';
+    certainty: 'server_projection';
+    value: T;
+} | {
+    status: 'unavailable';
+    certainty: 'unknown';
+    code: string;
+    httpStatus?: number;
+    message: string;
+    remedy: string;
+};
+export type TaskPreflight = {
+    taskId: string;
+    summary: 'eligible_to_attempt' | 'blocked' | 'unknown';
+    workflow: Observation<TaskActionabilityResponse>;
+    execution: Observation<AdmissionPreview>;
+    consistency: 'independent_observations';
+    limits: string[];
+};
+/** Compose native reads. This module cannot dispatch execution or infer grants. */
+export declare function readTaskPreflight(taskId: string, reads: {
+    workflow: () => Promise<unknown>;
+    execution: () => Promise<unknown>;
+}): Promise<TaskPreflight>;
+export declare function taskPreflightLines(report: TaskPreflight, bin?: string): string[];
+export {};

package/dist/lib/task-preflight.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readTaskPreflight = readTaskPreflight;
+exports.taskPreflightLines = taskPreflightLines;
+const task_admission_1 = require("./task-admission");
+const task_operations_1 = require("./task-operations");
+const LIMITS = [
+    'Workflow and execution checks are separate server observations, not an atomic reservation.',
+    'No Run, shell command, machine probe, or branch checkout was performed.',
+    'Tool availability, working-directory access, and successful provider execution remain unverified.',
+    'Starting rechecks current Task authorization, runtime admission, and tool permissions.',
+];
+function unavailable(error, label) {
+    const row = error && typeof error === 'object' ? error : {};
+    const status = typeof row.status === 'number' ? row.status : undefined;
+    let code = typeof row.code === 'string' && /^[A-Z][A-Z0-9_]{0,100}$/.test(row.code) ? row.code : undefined;
+    // Keep the native typed refusal without echoing an arbitrary response body,
+    // HTML proxy page, request URL, or credential into diagnostics.
+    if (!code && typeof row.body === 'string') {
+        try {
+            const body = JSON.parse(row.body);
+            if (typeof body?.code === 'string' && /^[A-Z][A-Z0-9_]{0,100}$/.test(body.code))
+                code = body.code;
+        }
+        catch { /* non-JSON server refusal */ }
+    }
+    const remedy = status === 401
+        ? 'Restore the current CLI sign-in or delegated runtime credential, then repeat this read-only check.'
+        : status === 403
+            ? 'Ask the Task owner or an authorized administrator to check your access; preflight does not bypass permissions.'
+            : status === 404
+                ? 'Check the Task reference and server support for this diagnostic. No start fallback was attempted.'
+                : 'Read tasks actionability and tasks start --dry-run separately for the native refusal, then repeat preflight after resolving it.';
+    return {
+        status: 'unavailable', certainty: 'unknown', code: code || 'TASK_PREFLIGHT_UNAVAILABLE',
+        ...(status ? { httpStatus: status } : {}),
+        message: `${label} could not be confirmed${status ? ` (HTTP ${status})` : ''}.`, remedy,
+    };
+}
+function isWorkflow(value, taskId) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    const a = row.actionability;
+    return row.taskId === taskId && Boolean(a &&
+        ['ready', 'running', 'waiting', 'terminal'].includes(a.state) &&
+        ['agent', 'human', 'system', 'external', 'none'].includes(a.nextActor) &&
+        typeof a.reasonCode === 'string' && typeof a.reason === 'string' &&
+        (a.actorRefs === undefined || Array.isArray(a.actorRefs) && a.actorRefs.every(ref => ref && ['user', 'agent'].includes(ref.kind) && typeof ref.id === 'string')) &&
+        Array.isArray(a.allowedActions) && a.allowedActions.every(action => action &&
+        typeof action.action === 'string' && (action.targetId === undefined || typeof action.targetId === 'string')));
+}
+function isPreview(value, taskId) {
+    if (!(0, task_admission_1.isAdmissionPreview)(value) || value.taskId !== taskId)
+        return false;
+    const a = value.executionAdmission;
+    return Boolean(typeof a.unattended === 'boolean' && typeof a.approverAvailable === 'boolean' &&
+        (a.constraints === undefined || Array.isArray(a.constraints) && a.constraints.every(c => c &&
+            (c.message === undefined || typeof c.message === 'string') &&
+            (c.requiredAction === undefined || typeof c.requiredAction === 'string'))) &&
+        (a.permission === undefined || a.permission && typeof a.permission === 'object' &&
+            (a.permission.mode == null || typeof a.permission.mode === 'string') &&
+            (a.permission.source === undefined || typeof a.permission.source === 'string')) &&
+        (a.shell === undefined || a.shell && typeof a.shell === 'object' &&
+            (a.shell.state === undefined || typeof a.shell.state === 'string')) &&
+        (a.workingDirectory === undefined || a.workingDirectory &&
+            (a.workingDirectory.path === null || typeof a.workingDirectory.path === 'string') &&
+            typeof a.workingDirectory.source === 'string'));
+}
+/** Compose native reads. This module cannot dispatch execution or infer grants. */
+async function readTaskPreflight(taskId, reads) {
+    const [workflowResult, executionResult] = await Promise.allSettled([
+        Promise.resolve().then(reads.workflow), Promise.resolve().then(reads.execution),
+    ]);
+    const workflow = workflowResult.status === 'fulfilled' && isWorkflow(workflowResult.value, taskId)
+        ? { status: 'observed', certainty: 'server_projection', value: workflowResult.value }
+        : unavailable(workflowResult.status === 'rejected' ? workflowResult.reason : { code: 'TASK_ACTIONABILITY_UNSUPPORTED' }, 'Workflow actionability');
+    const execution = executionResult.status === 'fulfilled' && isPreview(executionResult.value, taskId)
+        ? { status: 'observed', certainty: 'server_projection', value: executionResult.value }
+        : unavailable(executionResult.status === 'rejected' ? executionResult.reason : { code: 'TASK_START_PREVIEW_UNSUPPORTED' }, 'Execution preview');
+    // actionability.revision is the attention revision, not Task.version from
+    // start-preview. Equal numbers would not prove the reads shared a snapshot.
+    const workflowBlocked = workflow.status === 'observed' &&
+        !workflow.value.actionability.allowedActions.some(action => action.action === 'start_task');
+    const executionBlocked = execution.status === 'observed' && execution.value.executionAdmission.state === 'blocked';
+    const summary = workflowBlocked || executionBlocked ? 'blocked'
+        : workflow.status === 'unavailable' || execution.status === 'unavailable' ||
+            execution.value.executionAdmission.state !== 'ready' ? 'unknown'
+            : 'eligible_to_attempt';
+    return { taskId, summary, workflow, execution, consistency: 'independent_observations', limits: [...LIMITS] };
+}
+function taskPreflightLines(report, bin = 'skrr') {
+    const lines = [`Task preflight: ${report.taskId}`, `Start eligibility: ${report.summary.replaceAll('_', ' ')} (current server projections)`];
+    if (report.workflow.status === 'observed') {
+        const a = report.workflow.value.actionability;
+        lines.push('', `Workflow: ${a.state} (server projection)`, `Next actor: ${a.nextActor}`, `Why: ${a.reason} [${a.reasonCode}]`);
+        if (a.actorRefs?.length)
+            lines.push(`Eligible actors: ${a.actorRefs.map(ref => `${ref.kind}:${ref.id}`).join(', ')}`);
+        for (const action of a.allowedActions) {
+            const command = (0, task_operations_1.taskActionCommand)(action.action, report.taskId, action.targetId, bin, {
+                allowedActions: a.allowedActions,
+            });
+            lines.push(`  ${action.action}${command ? ` → ${command}` : ' (no single CLI remedy is mapped)'}`);
+        }
+        lines.push('Allowed actions describe the workflow; the caller must still have permission to perform them.');
+    }
+    else
+        lines.push('', `Workflow: unknown. ${report.workflow.message} [${report.workflow.code}]`, `Next step: ${report.workflow.remedy}`);
+    if (report.execution.status === 'observed') {
+        lines.push('', 'Execution prerequisites (server configuration; no execution test):', ...(0, task_admission_1.admissionLines)(report.execution.value.executionAdmission));
+        if (report.execution.value.executionAdmission.shell?.state) {
+            lines.push(`Shell approval prerequisites: ${report.execution.value.executionAdmission.shell.state} (policy only; shell execution unverified).`);
+        }
+        if (report.execution.value.executionAdmission.constraints?.length)
+            lines.push('Execution remedy owner: not reported by this server; ask the authorized Agent or Harness administrator.');
+    }
+    else
+        lines.push('', `Execution: unknown. ${report.execution.message} [${report.execution.code}]`, `Next step: ${report.execution.remedy}`);
+    lines.push('', ...report.limits, `More operations: ${bin} tasks guide`);
+    return lines;
+}

package/dist/lib/task-resource-references.d.ts

@@ -0,0 +1,23 @@
+type RecordValue = Record<string, unknown>;
+export type TaskResourceReferenceCache = Map<string, Promise<unknown>>;
+export type TaskResourceReferenceOptions = {
+    existingTask?: RecordValue;
+    cache?: TaskResourceReferenceCache;
+    resolveSpace: (value: string) => Promise<string>;
+    getTask?: (id: string) => Promise<RecordValue>;
+    getProject?: (id: string) => Promise<RecordValue>;
+    listProjects?: (spaceId: string) => Promise<unknown>;
+    listGoals?: (spaceId: string) => Promise<unknown>;
+};
+export declare class TaskResourceReferenceError extends Error {
+    readonly code: string;
+    readonly candidates: RecordValue[];
+    constructor(code: string, message: string, candidates?: RecordValue[]);
+}
+/**
+ * Resolve structured-input names as well as flag names, before assignment
+ * defaults. UUIDs keep their existing native validation path. A Goal is a
+ * relationship, not containment: a qualified Goal never moves its Task.
+ */
+export declare function resolveTaskResourceReferences(payload: RecordValue, options: TaskResourceReferenceOptions): Promise<void>;
+export {};