@skrr-ai/cli 0.1.108 → 0.1.109

package/dist/commands/tasks/create-tree.js

@@ -5,6 +5,8 @@ exports.rerunWarning = rerunWarning;
 exports.derivedTreePrefix = derivedTreePrefix;
 exports.derivedPrefixWarning = derivedPrefixWarning;
 exports.partialFailureResult = partialFailureResult;
+exports.orderForCreation = orderForCreation;
+exports.describeDefaultAgentAssignment = describeDefaultAgentAssignment;
 exports.normalizeTreeRoots = normalizeTreeRoots;
 exports.planTree = planTree;
 const core_1 = require("@oclif/core");
@@ -13,6 +15,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const prompt_1 = require("../../lib/prompt");
 const task_batch_1 = require("../../lib/task-batch");
+const write_target_1 = require("../../lib/write-target");
 const tasks_1 = require("../../lib/tasks");
 /**
  * Nodes a re-run could not recognize: no externalKey of their own and no
@@ -52,7 +55,7 @@ function derivedPrefixWarning(prefix) {
     return {
         code: 'TREE_PREFIX_DERIVED',
         value: prefix,
-        hint: `No --external-key-prefix was given, so nodes are keyed "${prefix}/<tempId>" from the file's content: ` +
+        hint: `No --external-key-prefix was given, so nodes without their own externalKey are keyed "${prefix}/<tempId>" from the file's content: ` +
             're-running the same file updates these tasks instead of creating copies. Pass --fresh to create a second copy, ' +
             'or --external-key-prefix to choose your own keys.',
     };
@@ -60,14 +63,27 @@ function derivedPrefixWarning(prefix) {
 /**
  * What a half-applied tree reports (E4). The ids already created are the only
  * way to continue or clean up, and the failing call used to print none of them.
+ *
+ * Every confirmed id is in `mapping` however the run ended, and `summary` counts
+ * the three things a failure can leave: confirmed, UNKNOWN (submitted, outcome
+ * not established — it may exist) and not attempted. They are different next
+ * steps, and a count that folded them together was the thing the first report
+ * of OSK-S-440 could not rely on.
  */
 function partialFailureResult(args) {
     const { results, mapping, failedAt, total, prefix, warnings } = args;
+    const outcomes = (args.failures ?? []).map((f) => String(f.outcome));
     return {
         object: 'task_create_tree_result',
         ok: false,
         count: results.length,
         total,
+        summary: {
+            confirmed: results.length,
+            unknown: outcomes.filter((o) => o === 'unknown').length,
+            notAttempted: outcomes.filter((o) => o === 'not_attempted').length,
+            failed: outcomes.filter((o) => o === 'failed').length,
+        },
         created: results.map((r) => ({
             tempId: r.tempId,
             parentTempId: r.parentTempId,
@@ -80,18 +96,84 @@ function partialFailureResult(args) {
         failedAt,
         ...(args.failures ? { failures: args.failures } : {}),
         rerun: prefix || args.keyed
-            ? 'Re-run the same keyed file with --resume to confirm existing IDs and create only missing nodes. A submitted write may still finish; stable keys prevent duplicates.'
+            ? 'Re-run the same keyed file with --resume to confirm existing IDs and create only missing nodes; --verify lists what exists and what is missing without writing. A submitted write may still finish; stable keys prevent duplicates.'
             : 'Re-running creates un-keyed nodes again. Use mapping to continue by hand, or re-run with --external-key-prefix.',
+        ...(args.next && (prefix || args.keyed) ? { next: args.next } : {}),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
+/**
+ * Order nodes so everything a node depends on — its parent and every blocker —
+ * comes BEFORE it, keeping input order otherwise. The batch and the serial path
+ * both create in this order, so a parent id and a blocker id exist by the time a
+ * node that needs them is written.
+ *
+ * Also the place a bad `blockedByTempIds` is caught: before any request, naming
+ * the node, rather than as a per-row refusal after half the tree exists.
+ */
+function orderForCreation(planned) {
+    const byKey = new Map(planned.map((node) => [node.key, node]));
+    const errors = [];
+    const dependenciesOf = (node) => {
+        const out = [];
+        if (node.parentKey)
+            out.push(node.parentKey);
+        for (const blocker of node.blockerKeys ?? []) {
+            if (blocker === node.key) {
+                errors.push(`${node.key}: a node cannot block itself`);
+            }
+            else if (!byKey.has(blocker)) {
+                errors.push(`${node.key}: blockedByTempIds "${blocker}" does not match any node's tempId in this file ` +
+                    '(to block on a task that already exists, give its id in blockedByIds)');
+            }
+            else {
+                out.push(blocker);
+            }
+        }
+        return out;
+    };
+    const ordered = [];
+    const state = new Map();
+    const path = [];
+    const visit = (node) => {
+        const current = state.get(node.key);
+        if (current === 'done')
+            return;
+        if (current === 'visiting') {
+            const loop = [...path.slice(path.indexOf(node.key)), node.key];
+            errors.push(`dependency cycle: ${loop.join(' -> ')}`);
+            return;
+        }
+        state.set(node.key, 'visiting');
+        path.push(node.key);
+        for (const dependency of dependenciesOf(node)) {
+            const next = byKey.get(dependency);
+            if (next)
+                visit(next);
+        }
+        path.pop();
+        state.set(node.key, 'done');
+        ordered.push(node);
+    };
+    for (const node of planned)
+        visit(node);
+    return { ordered: errors.length > 0 ? planned : ordered, errors: [...new Set(errors)] };
+}
 class TasksCreateTree extends base_command_1.BaseCommand {
-    static description = 'Create a task tree from JSON. Use {"nodes":[{"tempId":"root","title":"Task","executionMode":"human","assigneeUserIds":["<user-id>"]}]} to avoid inheriting a Space lead agent.';
+    static description = 'Create a task tree from JSON and make every node exist. Recommended shape: ' +
+        '{"nodes":[{"tempId":"root","title":"Task","executionMode":"human","assigneeUserIds":["<user-id>"]}]} ' +
+        '(a "nodes" array, each node with optional "children"; {"root":{...,"children":[...]}} is accepted too). ' +
+        'Put "me" in assigneeUserIds for yourself and "blockedByTempIds":["<tempId>"] for dependencies. ' +
+        'Setting executionMode human with an explicit assignee avoids inheriting a Space lead agent. ' +
+        'Nodes with an externalKey (or under --external-key-prefix) are created once: a re-run, --resume or --verify finds them again.';
     static examples = [
         '<%= config.bin %> tasks create-tree --from-json tree.json --space <space-id> --json',
         '<%= config.bin %> tasks create-tree --from-json tree.json --space <space-id> --default-agent auto',
         '<%= config.bin %> tasks create-tree --from-json tree.json --external-key-prefix recursive-learning/ws0',
         '<%= config.bin %> tasks create-tree --from-json tree.json --dry-run --json',
+        '<%= config.bin %> tasks create-tree --from-json tree.json --external-key-prefix mine/ --verify --json',
+        '<%= config.bin %> tasks create-tree --from-json tree.json --external-key-prefix mine/ --resume',
+        '<%= config.bin %> tasks create-tree --from-json tree.json --space <space-id> --project OSK-P-1 --expect-target skrr.ai',
     ];
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output the create-tree result as JSON' }),
@@ -99,7 +181,13 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             description: 'Path to a JSON file (or "-" for stdin) describing the tree',
             required: true,
         }),
-        'dry-run': core_1.Flags.boolean({ description: 'Validate and print the plan without creating tasks' }),
+        'dry-run': core_1.Flags.boolean({
+            description: 'Validate and print the plan without creating tasks. Each node says whether it would be created or already exists.',
+        }),
+        verify: core_1.Flags.boolean({
+            description: 'Read-only: report which nodes of this tree already exist (matched by externalKey) and which are missing, and write nothing. Exits 1 when any is missing or cannot be checked.',
+            exclusive: ['fresh', 'resume', 'dry-run', 'no-batch'],
+        }),
         'external-key-prefix': core_1.Flags.string({
             description: 'Generate externalKey for nodes that omit one; enables idempotent re-runs. Defaults to a prefix derived from the file content (see --fresh)',
         }),
@@ -110,11 +198,18 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             description: 'Confirm existing stable-key nodes without patching them, then create only missing nodes. Use the unchanged keyed file after an incomplete result.',
             exclusive: ['fresh'],
         }),
+        'no-batch': core_1.Flags.boolean({
+            description: 'Create one task per request instead of through the batch route. Slower; use it to rule the batch route out. Nothing else needs it: a batch that the server answers in part is continued automatically.',
+        }),
         'default-agent': core_1.Flags.string({
             description: 'Override the automatic assignee for nodes with no assignee. Use "auto" to inherit the space lead agent; children inherit parent assignees first.',
         }),
         space: core_1.Flags.string({ description: 'Default space ID for all nodes' }),
         goal: core_1.Flags.string({ description: 'Default goal ID for all nodes' }),
+        project: core_1.Flags.string({
+            description: "Default project for all nodes: its id, its ref (OSK-P-3) or the externalKey it was filed under. A ref or key is read inside the node's space, so give --space (or a spaceId on the nodes).",
+        }),
+        ...write_target_1.expectTargetFlag,
     };
     async run() {
         this.requireAuth();
@@ -140,49 +235,82 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             ? undefined
             : derivedTreePrefix(input, topLevelDefaults);
         const keyPrefix = flags['external-key-prefix'] ?? derivedPrefix;
-        const planned = planTree(roots, {
-            defaults: topLevelDefaults,
-            externalKeyPrefix: keyPrefix,
-        });
+        let planned;
+        try {
+            planned = planTree(roots, {
+                defaults: topLevelDefaults,
+                externalKeyPrefix: keyPrefix,
+            });
+        }
+        catch (err) {
+            this.error(err.message, { exit: 1 });
+        }
+        // Only a node that actually took its key from the derived prefix makes that
+        // prefix worth a warning. A file whose every node names its own key (the
+        // shape an agent writes) was told about a prefix it never used.
+        const usedDerivedPrefix = Boolean(derivedPrefix) && planned.some((node) => node.keyDerived);
         const defaultAgentErrors = [];
+        const ordering = orderForCreation(planned);
+        defaultAgentErrors.push(...ordering.errors);
+        planned = ordering.ordered;
         const defaultAgentResolutions = {};
         const plannedByKey = new Map(planned.map((item) => [item.key, item]));
         const spaceCache = new Map();
         const parentTaskCache = new Map();
         const projectCache = new Map();
         const existingByKey = new Map();
+        // 1. Where does each node land? A parent or a project can decide the Space,
+        //    and a key means a task only within its Space — so scope comes first.
+        const scopes = new Map();
         for (const item of planned) {
-            let scope;
             try {
-                scope = await (0, tasks_1.resolveTaskCreateScope)(item.payload, {
-                    parentTaskCache,
-                    projectCache,
-                });
+                scopes.set(item.key, await (0, tasks_1.resolveTaskCreateScope)(item.payload, { parentTaskCache, projectCache }));
             }
             catch (err) {
                 defaultAgentErrors.push(`${item.key}: ${err.message}`);
-                continue;
             }
-            let existingTask = null;
-            if (typeof item.payload.externalKey === 'string' && item.payload.externalKey.trim()) {
-                try {
-                    const existing = await (0, tasks_1.findTaskByExternalKey)({
-                        externalKey: item.payload.externalKey,
-                        spaceId: item.payload.spaceId,
-                        goalId: item.payload.goalId,
-                    });
-                    if (existing.duplicates.length > 0) {
-                        defaultAgentErrors.push(`${item.key}: externalKey ${item.payload.externalKey} matched multiple tasks`);
-                        continue;
-                    }
-                    existingTask = existing.task;
-                }
-                catch (err) {
-                    defaultAgentErrors.push(`${item.key}: ${err.message}`);
-                    continue;
-                }
+        }
+        // 2. Which nodes already exist? One bulk read, not one request per node.
+        const lookups = planned
+            .filter((item) => scopes.has(item.key) &&
+            typeof item.payload.externalKey === 'string' &&
+            item.payload.externalKey.trim())
+            .map((item) => ({
+            key: item.key,
+            lookup: {
+                externalKey: item.payload.externalKey,
+                spaceId: item.payload.spaceId,
+                goalId: item.payload.goalId,
+            },
+        }));
+        const hits = await (0, tasks_1.findTasksByExternalKeys)(lookups.map((entry) => entry.lookup));
+        const unverifiable = [];
+        for (const { key, lookup } of lookups) {
+            const hit = hits.get((0, tasks_1.externalKeyLookupId)(lookup));
+            if (hit?.error) {
+                defaultAgentErrors.push(`${key}: ${hit.error.message}`);
+                unverifiable.push({ tempId: key, reason: hit.error.message });
             }
-            existingByKey.set(item.key, existingTask);
+            else if (hit && hit.duplicates.length > 0) {
+                defaultAgentErrors.push(`${key}: externalKey ${lookup.externalKey} matched multiple tasks`);
+                unverifiable.push({ tempId: key, reason: 'externalKey matched multiple tasks' });
+            }
+            else {
+                existingByKey.set(key, hit?.task ?? null);
+            }
+        }
+        if (flags.verify) {
+            await this.verifyTree(planned, existingByKey, unverifiable, flags);
+            return;
+        }
+        // 3. Who owns each node? `me`, names and emails become ids first, so every
+        //    decision below sees what will actually be written.
+        for (const item of planned) {
+            const scope = scopes.get(item.key);
+            if (!scope)
+                continue;
+            await this.resolveAssigneesInPayload(item.payload);
+            const existingTask = existingByKey.get(item.key) ?? null;
             const parentPayload = item.parentKey
                 ? (existingByKey.get(item.parentKey) ?? plannedByKey.get(item.parentKey)?.payload)
                 : scope.parentTask;
@@ -218,7 +346,10 @@ class TasksCreateTree extends base_command_1.BaseCommand {
         const errors = [
             ...defaultAgentErrors,
             ...(flags.resume && unkeyedNodes(planned).length
-                ? ['--resume requires an externalKey for every node; supply --external-key-prefix and do not use --fresh'] : []),
+                ? [
+                    '--resume requires an externalKey for every node; supply --external-key-prefix and do not use --fresh',
+                ]
+                : []),
             ...planned.flatMap(({ key, payload }) => (0, tasks_1.validateTaskCreatePayload)(payload).map((error) => `${key}: ${error}`)),
         ];
         if (errors.length > 0) {
@@ -230,6 +361,12 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             this.exit(1);
             return;
         }
+        // An agent that would be put in charge by DEFAULT — the session's own agent,
+        // a parent's, the space lead — is the one assignment a person did not write
+        // and may not expect, and an agent with auto-execution may start work on it.
+        // Say so before anything is written, not only inside a dry run (OSK-S-440 #9).
+        const agentAssignment = describeDefaultAgentAssignment(defaultAgentResolutions);
+        const noteworthyAssignment = agentAssignment ? [agentAssignment] : [];
         if (flags['dry-run']) {
             const result = {
                 object: 'task_create_tree_dry_run',
@@ -238,16 +375,23 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                 ...(() => {
                     const dryWarnings = [
                         rerunWarning(planned, keyPrefix),
-                        derivedPrefix ? derivedPrefixWarning(derivedPrefix) : undefined,
+                        usedDerivedPrefix && derivedPrefix ? derivedPrefixWarning(derivedPrefix) : undefined,
+                        ...noteworthyAssignment,
                     ].filter((w) => w !== undefined);
                     return dryWarnings.length > 0 ? { warnings: dryWarnings } : {};
                 })(),
+                summary: {
+                    create: planned.filter((item) => !existingByKey.get(item.key)).length,
+                    [flags.resume ? 'existing' : 'update']: planned.filter((item) => existingByKey.get(item.key)).length,
+                },
                 defaultAgents: defaultAgentResolutions,
                 nodes: planned.map((item) => ({
                     tempId: item.key,
                     parentTempId: item.parentKey,
+                    ...(item.blockerKeys?.length ? { blockedByTempIds: item.blockerKeys } : {}),
                     title: item.payload.title,
                     externalKey: item.payload.externalKey,
+                    action: plannedAction(existingByKey.get(item.key), Boolean(flags.resume)),
                     payload: item.payload,
                 })),
             };
@@ -262,17 +406,27 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             return;
         }
         const treeWarning = rerunWarning(planned, keyPrefix);
-        const derivedWarning = derivedPrefix ? derivedPrefixWarning(derivedPrefix) : undefined;
+        const derivedWarning = usedDerivedPrefix && derivedPrefix ? derivedPrefixWarning(derivedPrefix) : undefined;
         const warnings = [
             ...(treeWarning ? [treeWarning] : []),
             ...(derivedWarning ? [derivedWarning] : []),
+            ...noteworthyAssignment,
         ];
         if (treeWarning && !flags.json)
             process.stderr.write(`Warning: ${treeWarning.hint}\n`);
         if (derivedWarning && !flags.json)
             process.stderr.write(`Note: ${derivedWarning.hint}\n`);
+        if (agentAssignment && process.stderr.isTTY) {
+            process.stderr.write(`Warning: ${agentAssignment.hint}\n`);
+        }
+        // Everything above only read. From here a request writes, so say where, and
+        // honour a caller's `--expect-target` before the first one.
+        const target = await this.assertWriteTarget(flags['expect-target']);
         const mapping = {};
         const results = [];
+        const startedAt = Date.now();
+        let rounds = 0;
+        const next = this.nextCommand(flags);
         // A half-applied tree reports the ids it did create; the only way back.
         const reportPartial = (item, failure, err, failures) => {
             if (results.length === 0 && !failures)
@@ -285,6 +439,7 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                 keyed: unkeyedNodes(planned).length === 0,
                 warnings,
                 failures,
+                next,
                 failedAt: {
                     tempId: item.key,
                     ...(item.parentKey ? { parentTempId: item.parentKey } : {}),
@@ -293,7 +448,7 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                 },
             });
             if (flags.json) {
-                this.log(JSON.stringify(partial, null, 2));
+                this.log(JSON.stringify({ ...partial, target }, null, 2));
                 process.exitCode = partial.failedAt.error.retryable ? 5 : 1;
                 this.exit(partial.failedAt.error.retryable ? 5 : 1);
             }
@@ -301,6 +456,8 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             for (const [tempId, id] of Object.entries(mapping))
                 this.log(`- ${tempId} -> ${id}`);
             this.log(partial.rerun);
+            if (partial.next)
+                this.log(`Next: ${partial.next}`);
             if (failures) {
                 for (const row of failures) {
                     const detail = row.error;
@@ -311,8 +468,23 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             }
             this.handleApiError(err);
         };
+        // Blockers a node names by tempId, as the real ids the serial path needs.
+        const blockerIdsFor = (item) => {
+            const ids = [];
+            for (const blockerKey of item.blockerKeys ?? []) {
+                const id = mapping[blockerKey];
+                if (!id) {
+                    this.error(`Blocker tempId "${blockerKey}" was not created before "${item.key}"`, {
+                        exit: 1,
+                    });
+                }
+                ids.push(id);
+            }
+            return ids;
+        };
         // The serial path: one request per node. Used for updates of existing keyed
-        // nodes, and for every create against a server without the batch route.
+        // nodes, for every create against a server without the batch route, and for
+        // everything under --no-batch.
         const applySerial = async (item) => {
             const payload = { ...item.payload };
             if (item.parentKey) {
@@ -323,6 +495,7 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                     });
                 }
             }
+            const blockerIds = blockerIdsFor(item);
             let action;
             let task;
             try {
@@ -331,6 +504,9 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                     if (existingTask) {
                         action = 'updated';
                         const patch = (0, tasks_1.removeUndefinedFields)((0, tasks_1.createPatchFromCreatePayload)(payload));
+                        // Adding is idempotent, so a re-run never duplicates or drops an edge.
+                        if (blockerIds.length > 0)
+                            patch.addBlockedByIds = blockerIds;
                         task = await data_provider_1.dataService.updateTask({
                             taskId: (0, tasks_1.taskId)(existingTask),
                             data: patch,
@@ -338,11 +514,27 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                     }
                     else {
                         action = 'created';
+                        if (blockerIds.length > 0) {
+                            payload.blockedByIds = [
+                                ...new Set([
+                                    ...(payload.blockedByIds ?? []),
+                                    ...blockerIds,
+                                ]),
+                            ];
+                        }
                         task = await data_provider_1.dataService.createTask(payload);
                     }
                 }
                 else {
                     action = 'created';
+                    if (blockerIds.length > 0) {
+                        payload.blockedByIds = [
+                            ...new Set([
+                                ...(payload.blockedByIds ?? []),
+                                ...blockerIds,
+                            ]),
+                        ];
+                    }
                     task = await data_provider_1.dataService.createTask(payload);
                 }
             }
@@ -362,9 +554,19 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                 task,
             });
         };
-        // New nodes go to POST /api/tasks/batch in chunks. `batchAvailable` flips off
-        // the first time the server answers 404/405, and every later node is serial.
-        let batchAvailable = true;
+        // A person watching sees the tree being built; anything capturing output
+        // sees nothing extra (the answer is the JSON / summary at the end).
+        const onProgress = process.stderr.isTTY
+            ? (p) => {
+                process.stderr.write(p.waiting
+                    ? `Waiting ${Math.max(1, Math.round(p.waiting.ms / 1000))}s before trying again (${p.waiting.reason}); ${p.confirmed} of ${p.total} confirmed.\n`
+                    : `Confirmed ${p.confirmed} of ${p.total} (request ${p.round}, ${Math.round(p.elapsedMs / 1000)}s).\n`);
+            }
+            : undefined;
+        // New nodes go to POST /api/tasks/batch, and the batch is driven until every
+        // one exists (createNodesViaBatch). `batchAvailable` flips off the first time
+        // the server answers 404/405, or under --no-batch, and every later node is serial.
+        let batchAvailable = !flags['no-batch'];
         let pending = [];
         const flushPending = async () => {
             const nodes = pending;
@@ -372,8 +574,14 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             if (nodes.length === 0)
                 return;
             if (batchAvailable) {
-                const outcome = await (0, task_batch_1.createNodesViaBatch)(nodes.map((n) => ({ key: n.key, parentKey: n.parentKey, payload: n.payload })), mapping);
+                const outcome = await (0, task_batch_1.createNodesViaBatch)(nodes.map((n) => ({
+                    key: n.key,
+                    parentKey: n.parentKey,
+                    blockerKeys: n.blockerKeys,
+                    payload: n.payload,
+                })), mapping, { onProgress });
                 if (outcome.supported) {
+                    rounds += outcome.rounds;
                     const byKey = new Map(nodes.map((n) => [n.key, n]));
                     for (const row of outcome.rows) {
                         const node = byKey.get(row.key);
@@ -399,7 +607,8 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                             ...(failure.error.code ? { code: failure.error.code } : {}),
                         });
                         reportPartial(node, failure.error, err, outcome.failures.map((f) => ({
-                            tempId: f.key, outcome: f.outcome ?? (f.skipped ? 'not_attempted' : 'failed'),
+                            tempId: f.key,
+                            outcome: f.outcome ?? (f.skipped ? 'not_attempted' : 'failed'),
                             externalKey: f.externalKey ?? byKey.get(f.key)?.payload.externalKey,
                             error: f.error,
                         })));
@@ -419,8 +628,15 @@ class TasksCreateTree extends base_command_1.BaseCommand {
                 if (flags.resume) {
                     const id = (0, tasks_1.taskId)(existingTask);
                     mapping[item.key] = id;
-                    results.push({ tempId: item.key, parentTempId: item.parentKey, id, action: 'existing',
-                        externalKey: item.payload.externalKey, title: existingTask.title ?? item.payload.title, task: existingTask });
+                    results.push({
+                        tempId: item.key,
+                        parentTempId: item.parentKey,
+                        id,
+                        action: 'existing',
+                        externalKey: item.payload.externalKey,
+                        title: existingTask.title ?? item.payload.title,
+                        task: existingTask,
+                    });
                 }
                 else
                     await applySerial(item);
@@ -436,6 +652,8 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             ...(warnings.length > 0 ? { warnings } : {}),
             count: results.length,
             defaultAgents: defaultAgentResolutions,
+            target,
+            timing: { elapsedMs: Date.now() - startedAt, requests: rounds },
             mapping,
             results,
         };
@@ -449,8 +667,135 @@ class TasksCreateTree extends base_command_1.BaseCommand {
             this.log(`- ${item.tempId}: ${item.action} ${(0, tasks_1.formatTaskLabel)(task)}`);
         }
     }
+    /**
+     * `--verify`: which nodes of this tree exist, and which do not. Read-only by
+     * construction — it is reached before anything that writes — so it is safe to
+     * run at any time, as often as wanted, against a tree of any size.
+     */
+    async verifyTree(planned, existingByKey, unverifiable, flags) {
+        const cannotCheck = new Map(unverifiable.map((u) => [u.tempId, u.reason]));
+        for (const key of unkeyedNodes(planned)) {
+            if (!cannotCheck.has(key)) {
+                cannotCheck.set(key, 'no externalKey, so nothing can recognise it; give an externalKey or --external-key-prefix');
+            }
+        }
+        const existing = [];
+        const missing = [];
+        for (const item of planned) {
+            if (cannotCheck.has(item.key))
+                continue;
+            const task = existingByKey.get(item.key);
+            if (task) {
+                existing.push({
+                    tempId: item.key,
+                    id: (0, tasks_1.taskId)(task),
+                    ...(typeof task.identifier === 'string' ? { identifier: task.identifier } : {}),
+                    externalKey: item.payload.externalKey,
+                    title: task.title ?? item.payload.title,
+                });
+            }
+            else {
+                missing.push({
+                    tempId: item.key,
+                    ...(item.parentKey ? { parentTempId: item.parentKey } : {}),
+                    externalKey: item.payload.externalKey,
+                    title: item.payload.title,
+                });
+            }
+        }
+        const ok = missing.length === 0 && cannotCheck.size === 0;
+        const result = {
+            object: 'task_create_tree_verification',
+            ok,
+            total: planned.length,
+            summary: {
+                existing: existing.length,
+                missing: missing.length,
+                unverifiable: cannotCheck.size,
+            },
+            existing,
+            missing,
+            unverifiable: [...cannotCheck].map(([tempId, reason]) => ({ tempId, reason })),
+            target: await this.describeWriteTarget(),
+            ...(missing.length > 0 ? { next: this.nextCommand(flags) } : {}),
+        };
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            this.log(`${existing.length} of ${planned.length} node(s) exist; ${missing.length} missing` +
+                (cannotCheck.size ? `; ${cannotCheck.size} cannot be checked` : '') +
+                '.');
+            for (const row of missing)
+                this.log(`- missing: ${String(row.tempId)} (${String(row.externalKey)})`);
+            for (const [tempId, reason] of cannotCheck)
+                this.log(`- cannot check: ${tempId} — ${reason}`);
+            if (result.next)
+                this.log(`Next: ${result.next}`);
+        }
+        if (!ok)
+            this.exit(1);
+    }
+    /**
+     * The command that continues this tree, as it should be typed: this
+     * invocation's own input and scope, plus `--resume`. Rebuilt from the parsed
+     * flags rather than echoed from argv, so it is the same whether the person
+     * typed `--space x` or `--space=x`, and so it can say plainly when the input
+     * came from stdin and cannot be replayed from a path.
+     */
+    nextCommand(flags) {
+        const quote = (value) => /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+        const input = flags['from-json'];
+        const parts = [
+            this.config.bin,
+            'tasks',
+            'create-tree',
+            '--from-json',
+            input === '-' ? '<the same JSON on stdin>' : quote(String(input ?? '<file>')),
+        ];
+        for (const name of ['space', 'goal', 'project', 'external-key-prefix', 'default-agent']) {
+            const value = flags[name];
+            if (typeof value === 'string' && value)
+                parts.push(`--${name}`, quote(value));
+        }
+        for (const value of flags['expect-target'] ?? []) {
+            parts.push('--expect-target', quote(value));
+        }
+        if (flags.json)
+            parts.push('--json');
+        parts.push('--resume');
+        return parts.join(' ');
+    }
 }
 exports.default = TasksCreateTree;
+/** What a dry run says will happen to a node: create it, update it, or leave it (`--resume`). */
+function plannedAction(existing, resume) {
+    if (!existing)
+        return 'create';
+    return resume ? 'existing' : 'update';
+}
+/**
+ * The note that names an Agent put in charge of nodes by DEFAULT, or undefined
+ * when no node was. Sources a person wrote themselves (`explicit-assignee`,
+ * `provided` — an operator's own `--default-agent`) are not surprises; the
+ * session's agent, a parent's, or the space lead are.
+ */
+function describeDefaultAgentAssignment(resolutions) {
+    const surprising = Object.values(resolutions).filter((r) => r?.applied &&
+        (r.agentIds?.length ?? 0) > 0 &&
+        (r.source === 'caller-agent' || r.source === 'parent' || r.source === 'space-lead'));
+    if (surprising.length === 0)
+        return undefined;
+    const agentIds = [...new Set(surprising.flatMap((r) => r.agentIds ?? []))];
+    const sources = [...new Set(surprising.map((r) => r.source))];
+    return {
+        code: 'DEFAULT_AGENT_ASSIGNED',
+        value: { count: surprising.length, agentIds, sources },
+        hint: `${surprising.length} node(s) will be assigned to agent ${agentIds.join(', ')} by default (${sources.join(', ')}), ` +
+            'and a Space with auto-execution may start them. To keep them with you instead, put "executionMode":"human" and ' +
+            '"assigneeUserIds":["me"] on the nodes, or pass --default-agent with the assignee you mean.',
+    };
+}
 function normalizeTreeRoots(input) {
     const root = input.root;
     const nodes = input.nodes ?? input.tasks;
@@ -486,6 +831,7 @@ function normalizeDefaults(input, flags) {
         ...defaults,
         spaceId: flags.space ?? defaults.spaceId,
         goalId: flags.goal ?? defaults.goalId,
+        projectId: flags.project ?? defaults.projectId,
     });
 }
 function planTree(roots, opts) {
@@ -497,17 +843,37 @@ function planTree(roots, opts) {
             throw new Error(`Duplicate tree tempId/path key: ${key}`);
         }
         seen.add(key);
+        const blockerKeys = readBlockerKeys(node, key);
         const payload = nodePayload(node, opts.defaults);
+        let keyDerived = false;
         if (!payload.externalKey && opts.externalKeyPrefix) {
             payload.externalKey = `${opts.externalKeyPrefix.replace(/\/+$/, '')}/${key}`;
+            keyDerived = true;
         }
-        planned.push({ key, parentKey, node, payload });
+        planned.push({
+            key,
+            parentKey,
+            ...(blockerKeys.length ? { blockerKeys } : {}),
+            ...(keyDerived ? { keyDerived } : {}),
+            node,
+            payload,
+        });
         const children = Array.isArray(node.children) ? node.children : [];
         children.forEach((child, index) => visit(child, [...path, index], key));
     };
     roots.forEach((root, index) => visit(root, [index]));
     return planned;
 }
+/** `blockedByTempIds` as a clean list of the tempIds a node names, or a precise refusal. */
+function readBlockerKeys(node, key) {
+    const raw = node.blockedByTempIds;
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || raw.some((entry) => typeof entry !== 'string' || !entry.trim())) {
+        throw new Error(`Node "${key}": blockedByTempIds must be an array of tempIds`);
+    }
+    return [...new Set(raw.map((entry) => entry.trim()))];
+}
 function nodeKey(node, path) {
     const temp = node.tempId ?? node.temp_id ?? node.id;
     if (typeof temp === 'string' && temp.trim())
@@ -515,6 +881,6 @@ function nodeKey(node, path) {
     return path.join('.');
 }
 function nodePayload(node, defaults) {
-    const { children: _children, tempId: _tempId, temp_id: _tempIdSnake, id: _id, ...rest } = node;
+    const { children: _children, tempId: _tempId, temp_id: _tempIdSnake, id: _id, blockedByTempIds: _blockedByTempIds, ...rest } = node;
     return (0, tasks_1.buildTaskCreatePayload)({ ...defaults, ...rest }, {});
 }