@fitlab-ai/agent-infra 0.9.10 → 0.9.11

package/dist/lib/task/commands/decisions.js

@@ -3,19 +3,18 @@ import path from 'node:path';
 import { formatTable } from '../../table.js';
 import { parseTaskScope } from '../command-options.js';
 import { resolveTaskContext } from '../resolve-ref.js';
-import { isReviewStage, parseLedger } from '../ledger.js';
+import { isReviewStage, parseLedgerDocument } from '../ledger.js';
 import { listDecisionItems, selectDecisionItem } from '../decision-items.js';
-import { extractSubSection } from '../sections.js';
+import { normalizeDecisionDetailForDisplay, parseDecisionEvidence, resolveDecisionDetail } from '../decision-details.js';
 const USAGE = `Usage: ai task decisions [--task <ref> | -t <ref>] [--item <selector> | -i <selector>] [options]
-       ai task decisions <ref> [selector] [options]
 
 Shows what still needs a maintainer's decision. Without a selector, it lists
 the choices. With a selector, it shows the explanation and how to respond.
 Read-only.
 
-  Omit <ref>     Resolve the unique active task for the current branch.
-  <ref>          Legacy positional task ref.
-  [selector]     Ordinal (1-based) or ledger id (e.g. 'PL-3') to show one item's detail.
+  Omit the scope  Resolve the unique active task for the current branch.
+  --task/-t <ref> Select a task explicitly.
+  --item/-i <s>   Ordinal (1-based) or ledger id (e.g. 'PL-3') to show one item's detail.
 
 Options:
   -i, --item <s>    Select an item when task scope is implicit or flag-based.
@@ -53,15 +52,8 @@ function parseArgs(args) {
             i += 1;
         }
         else if (a.startsWith('--item=')) {
-            if (out.item !== undefined) {
-                fail("duplicate option '--item'");
-                return null;
-            }
-            out.item = a.slice('--item='.length);
-            if (out.item === '') {
-                fail('--item requires a value');
-                return null;
-            }
+            fail("--item=... is not supported; use --item <selector> or -i <selector>");
+            return null;
         }
         else if (a === '--stage') {
             const v = args[i + 1];
@@ -97,48 +89,26 @@ function parseArgs(args) {
     }
     return out;
 }
-// Parse `<file>.md#anchor` evidence into its filename, when present.
-function evidenceFile(evidence) {
-    const m = /([\w.-]+\.md)#/.exec(evidence);
-    return m ? m[1] : null;
-}
-function roundOf(file) {
-    const m = /-r(\d+)\.md$/.exec(file);
-    return m ? Number.parseInt(m[1], 10) : 1;
-}
-// Locate the `### {ledger-id}` detail block for a row. Prefer the artifact named by the
-// row's evidence anchor; otherwise scan analysis/plan/code artifacts and return
-// the block from the highest-round file that contains it. Returns '' when none
-// is found (caller degrades gracefully — plan B3).
 function findDetailBlock(row, taskDir) {
-    const hinted = evidenceFile(row.evidence);
-    if (hinted) {
-        const p = path.join(taskDir, hinted);
-        if (fs.existsSync(p)) {
-            const block = extractSubSection(fs.readFileSync(p, 'utf8'), row.id);
-            if (block)
-                return block;
-        }
-    }
-    let best = '';
-    let bestRound = -1;
-    let entries;
+    const evidence = parseDecisionEvidence(row.evidence);
+    if (!evidence.ok)
+        return { status: 'invalid', reason: `invalid evidence '${row.evidence}'` };
+    const artifactPath = path.join(taskDir, evidence.artifact);
+    if (!fs.existsSync(artifactPath))
+        return { status: 'missing', reason: `artifact '${evidence.artifact}' is missing` };
+    let artifactContent;
     try {
-        entries = fs.readdirSync(taskDir);
+        artifactContent = fs.readFileSync(artifactPath, 'utf8');
     }
     catch {
-        return '';
+        return { status: 'missing', reason: `artifact '${evidence.artifact}' cannot be read` };
     }
-    for (const file of entries) {
-        if (!/^(analysis|plan|code)(-r\d+)?\.md$/.test(file))
-            continue;
-        const block = extractSubSection(fs.readFileSync(path.join(taskDir, file), 'utf8'), row.id);
-        if (block && roundOf(file) > bestRound) {
-            best = block;
-            bestRound = roundOf(file);
-        }
-    }
-    return best;
+    const resolved = resolveDecisionDetail(artifactContent, row.id, evidence.anchor);
+    if (resolved.status === 'found')
+        return { status: 'found', content: normalizeDecisionDetailForDisplay(resolved.block) };
+    if (resolved.status === 'ambiguous')
+        return { status: 'ambiguous', reason: resolved.reason };
+    return { status: 'missing', reason: resolved.reason };
 }
 // Pull the `## 人工裁决` record lines that mention this ledger id, so a decided item
 // shows the human's recorded ruling alongside its detail block.
@@ -160,9 +130,9 @@ function findDecisionRecord(id, content) {
     return out;
 }
 function titleOf(row, taskDir) {
-    const block = findDetailBlock(row, taskDir);
-    if (block) {
-        const title = block
+    const detail = findDetailBlock(row, taskDir);
+    if (detail.status === 'found') {
+        const title = detail.content
             .split('\n')[0]
             .replace(/^###\s+/, '')
             .replace(/\s*\[needs-human-decision\]\s*$/, '')
@@ -174,7 +144,7 @@ function titleOf(row, taskDir) {
 function trackingOf(row) {
     return `stage=${row.stage} · severity=${row.severity} · status=${row.status} · evidence=${row.evidence}`;
 }
-function renderList(rows, format, taskDir) {
+function renderList(rows, format, taskDir, taskId) {
     if (rows.length === 0) {
         process.stdout.write('No pending decisions.\n');
         return;
@@ -193,10 +163,10 @@ function renderList(rows, format, taskDir) {
             `| ${sep.join(' | ')} |`,
             ...data.map((row) => `| ${row.join(' | ')} |`)
         ];
-        process.stdout.write(`${md.join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
+        process.stdout.write(`${md.join('\n')}\n\nView one item: ai task decisions --task ${taskId} --item <ordinal|ledger-id>\n`);
         return;
     }
-    process.stdout.write(`${formatTable(headers, data).join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
+    process.stdout.write(`${formatTable(headers, data).join('\n')}\n\nView one item: ai task decisions --task ${taskId} --item <ordinal|ledger-id>\n`);
 }
 function renderTracking(row, format) {
     if (format === 'markdown') {
@@ -216,29 +186,31 @@ function renderTracking(row, format) {
         `evidence: ${row.evidence}`
     ];
 }
-function renderDetail(rows, selector, format, taskDir, content) {
+function renderDetail(rows, selector, format, taskDir, content, taskId) {
     const selected = selectDecisionItem(rows, selector);
     if (!selected.ok) {
         fail(selected.message);
         return;
     }
     const r = selected.row;
-    const block = findDetailBlock(r, taskDir);
-    const title = titleOf(r, taskDir);
+    const detail = findDetailBlock(r, taskDir);
+    if (detail.status === 'invalid' || detail.status === 'ambiguous') {
+        fail(`cannot resolve ${r.id}: ${detail.reason}`);
+        return;
+    }
+    const block = detail.status === 'found' ? detail.content : '';
+    const title = block
+        ? block.split('\n')[0].replace(/^###\s+/, '').replace(/\s*\[needs-human-decision\]\s*$/, '').trim()
+            .replace(new RegExp(`^${r.id}\\s*[:：]\\s*`, 'i'), '').trim()
+        : '(explanation unavailable)';
     const lines = [];
     const decided = r.status === 'human-decided';
     if (format === 'markdown') {
         lines.push(`## ${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
-        if (!decided) {
-            lines.push('**How to record your choice**', `\`ai decide <task-ref> ${r.id} <your choice and rationale>\``, '');
-        }
         lines.push('**Original context**', '');
     }
     else {
         lines.push(`${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
-        if (!decided) {
-            lines.push('How to record your choice:', `ai decide <task-ref> ${r.id} <your choice and rationale>`, '');
-        }
         lines.push('Original context:');
     }
     if (block) {
@@ -252,6 +224,15 @@ function renderDetail(rows, selector, format, taskDir, content) {
         lines.push('', format === 'markdown' ? '**Recorded choice**' : 'Recorded choice:');
         lines.push(...(record.length ? record : ['No separate ruling record was found.']));
     }
+    if (!decided) {
+        lines.push('');
+        if (format === 'markdown') {
+            lines.push('**How to record your choice**', `\`ai decide --task ${taskId} --item ${r.id} <your choice and rationale>\``);
+        }
+        else {
+            lines.push('How to record your choice:', `ai decide --task ${taskId} --item ${r.id} <your choice and rationale>`);
+        }
+    }
     lines.push('', ...renderTracking(r, format));
     process.stdout.write(`${lines.join('\n')}\n`);
 }
@@ -279,43 +260,46 @@ function decisions(args = []) {
         fail(`invalid --format '${parsed.format}' (expected text|markdown)`);
         return;
     }
-    let taskRef = scope.taskRef;
-    let selector = parsed.item;
-    if (parsed.item !== undefined) {
-        if (parsed.positionals.length > 0) {
-            fail('positional task ref/selector cannot be combined with --item');
-            return;
-        }
-    }
-    else if (scope.explicit) {
-        if (parsed.positionals.length > 0) {
-            fail('positional task ref/selector cannot be combined with --task');
-            return;
-        }
-    }
-    else {
-        if (parsed.positionals.length > 2) {
-            fail('too many positional arguments');
-            return;
-        }
-        taskRef = parsed.positionals[0];
-        selector = parsed.positionals[1];
+    const taskRef = scope.taskRef;
+    const selector = parsed.item;
+    if (parsed.positionals.length > 0) {
+        fail('positional task ref/selector is not supported; use --task <ref> or -t <ref>, and --item <selector> or -i <selector>');
+        return;
     }
     const resolved = resolveTaskContext(taskRef);
     if (!resolved.ok) {
         fail(resolved.message);
         return;
     }
-    const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    const rows = listDecisionItems(parseLedger(content), {
+    let content;
+    let ledger;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        ledger = parseLedgerDocument(content);
+    }
+    catch (error) {
+        fail(`ledger unavailable [LEDGER_DOCUMENT_INVALID]: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    if (!ledger.present) {
+        fail('ledger unavailable [LEDGER_SECTION_MISSING]: review disagreement ledger section is missing');
+        return;
+    }
+    const rows = listDecisionItems(ledger.rows, {
         includeDecided: parsed.all,
         stage: parsed.stage
     });
     if (selector === undefined) {
-        renderList(rows, parsed.format, resolved.taskDir);
+        renderList(rows, parsed.format, resolved.taskDir, resolved.taskId);
     }
     else {
-        renderDetail(rows, selector, parsed.format, resolved.taskDir, content);
+        const selectionRows = /^[A-Za-z]+-\d+$/.test(selector)
+            ? listDecisionItems(ledger.rows, {
+                includeDecided: true,
+                stage: parsed.stage
+            })
+            : rows;
+        renderDetail(selectionRows, selector, parsed.format, resolved.taskDir, content, resolved.taskId);
     }
 }
 export { decisions };

package/dist/lib/task/commands/files.js

@@ -2,11 +2,11 @@ import { formatTable } from '../../table.js';
 import { parseTaskScope } from '../command-options.js';
 import { resolveTaskContext } from '../resolve-ref.js';
 import { enumerateArtifacts } from '../artifacts.js';
-const USAGE = `Usage: ai task files [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task files [--task <ref> | -t <ref>]
 
 Lists the artifacts in a task directory with stable numbers.
-  Omit <ref>   Resolve the unique active task for the current branch.
-  <ref>   Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope   Resolve the unique active task for the current branch.
+  --task/-t <ref> Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 Columns: # (artifact number, usable with 'ai task cat') / NAME / SIZE (bytes) / MTIME
 `;
@@ -33,12 +33,12 @@ function files(args = []) {
         process.exitCode = 1;
         return;
     }
-    if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-        process.stderr.write('ai task files: task ref must be provided once\n');
+    if (scope.positionals.length > 0) {
+        process.stderr.write('ai task files: positional task ref is not supported; use --task <ref> or -t <ref>\n');
         process.exitCode = 1;
         return;
     }
-    const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+    const resolved = resolveTaskContext(scope.taskRef);
     if (!resolved.ok) {
         process.stderr.write(`ai task files: ${resolved.message}\n`);
         process.exitCode = 1;

package/dist/lib/task/commands/grep.js

@@ -1,24 +1,19 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveTaskContext, resolveTaskRef, detectRepoRoot, enumerateTaskDirs } from '../resolve-ref.js';
+import { resolveTaskContext, resolveTaskRef } from '../resolve-ref.js';
 import { enumerateArtifacts, resolveArtifact } from '../artifacts.js';
 import { loadShortIdByTaskId } from '../short-id.js';
-const USAGE = `Usage: ai task grep <pattern> [ref] [artifact | N]
-       ai task grep <pattern> (--current | --task <ref> | -t <ref>) [artifact | N]
+const USAGE = `Usage: ai task grep [--current | --task <ref> | -t <ref>] <pattern> [artifact | N]
 
 Literal (non-regex) line search across task artifacts.
   <pattern>          Literal substring to match (NOT a regex). Case-sensitive by default.
-  [ref]              Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
-                     Omit to scan every task under active / blocked / completed
-                     (archive is skipped). With a ref, narrows to that single task
-                     (a TASK-id ref can also resolve an archived task).
-  [artifact | N]     Only valid with <ref>. Artifact filename (with or without '.md')
+  --current          Limit search to the unique active task for the current branch.
+  -t, --task <ref>   Limit search to an explicit task (bare short id or TASK-id).
+  [artifact | N]     Artifact filename (with or without '.md')
                      or the number from 'ai task files'. Narrows to a single artifact.
 
 Options:
   -i, --ignore-case  Case-insensitive matching.
-  --current          Limit search to the current task context.
-  -t, --task <ref>   Limit search to an explicit task.
   --                 Treat the rest as positional (use for patterns starting with '-').
 
 Output: '{taskId} [#short] {fileStem}:{line}: {matched-line}' (short id only for active tasks).
@@ -92,17 +87,9 @@ function grep(args = []) {
             continue;
         }
         if (!optsEnded && a.startsWith('--task=')) {
-            if (taskRef !== undefined) {
-                process.stderr.write("ai task grep: duplicate option '--task'\n");
-                process.exitCode = 1;
-                return;
-            }
-            taskRef = a.slice('--task='.length);
-            if (taskRef === '') {
-                process.stderr.write('ai task grep: --task requires a value\n');
-                process.exitCode = 1;
-                return;
-            }
+            process.stderr.write('ai task grep: --task=... is not supported; use --task <ref> or -t <ref>\n');
+            process.exitCode = 1;
+            return;
             continue;
         }
         if (!optsEnded && a.startsWith('-') && a !== '-') {
@@ -122,63 +109,40 @@ function grep(args = []) {
         process.exitCode = 1;
         return;
     }
-    if (positional.length > 3 || ((current || taskRef !== undefined) && positional.length > 2)) {
+    if (positional.length > 2) {
         process.stderr.write('ai task grep: too many arguments\n');
         process.exitCode = 1;
         return;
     }
-    let [pattern, ref, artifactOrN] = positional;
-    if (current || taskRef !== undefined) {
-        artifactOrN = ref;
-        ref = taskRef;
-    }
+    const [pattern, artifactOrN] = positional;
     const matcher = makeMatcher(pattern, ignoreCase);
     const chunks = [];
     const emit = (line) => chunks.push(line);
     let total = 0;
-    if (ref === undefined && !current) {
-        // No ref: full scan across active / blocked / completed (no archive).
-        let repoRoot;
+    const resolved = current || taskRef === undefined
+        ? resolveTaskContext()
+        : resolveTaskRef(taskRef);
+    if (!resolved.ok) {
+        process.stderr.write(`ai task grep: ${resolved.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const shortToken = loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId);
+    if (artifactOrN !== undefined) {
+        let artifactPath;
         try {
-            repoRoot = detectRepoRoot();
+            artifactPath = resolveArtifact(resolved.taskDir, artifactOrN);
         }
         catch (e) {
             process.stderr.write(`ai task grep: ${e.message}\n`);
             process.exitCode = 1;
             return;
         }
-        const shortMap = loadShortIdByTaskId(repoRoot);
-        for (const { taskId, taskDir } of enumerateTaskDirs(repoRoot)) {
-            const shortToken = shortMap.get(taskId);
-            for (const a of enumerateArtifacts(taskDir)) {
-                total += scanArtifact(taskId, shortToken, a.path, matcher, emit);
-            }
-        }
+        total += scanArtifact(resolved.taskId, shortToken, artifactPath, matcher, emit);
     }
     else {
-        const resolved = current ? resolveTaskContext() : resolveTaskRef(ref);
-        if (!resolved.ok) {
-            process.stderr.write(`ai task grep: ${resolved.message}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const shortToken = loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId);
-        if (artifactOrN !== undefined) {
-            let artifactPath;
-            try {
-                artifactPath = resolveArtifact(resolved.taskDir, artifactOrN);
-            }
-            catch (e) {
-                process.stderr.write(`ai task grep: ${e.message}\n`);
-                process.exitCode = 1;
-                return;
-            }
-            total += scanArtifact(resolved.taskId, shortToken, artifactPath, matcher, emit);
-        }
-        else {
-            for (const a of enumerateArtifacts(resolved.taskDir)) {
-                total += scanArtifact(resolved.taskId, shortToken, a.path, matcher, emit);
-            }
+        for (const a of enumerateArtifacts(resolved.taskDir)) {
+            total += scanArtifact(resolved.taskId, shortToken, a.path, matcher, emit);
         }
     }
     if (total === 0) {

package/dist/lib/task/commands/issue-body.js

@@ -4,11 +4,11 @@ import { resolveTaskContext } from '../resolve-ref.js';
 import { extractTitle } from '../frontmatter.js';
 import { extractSection, findSectionHeading } from '../sections.js';
 import { renderTemplateBody, PLACEHOLDER } from '../issue-form.js';
-const USAGE = `Usage: ai task issue-body [<ref> | --task <ref> | -t <ref>] [--template <path>]
+const USAGE = `Usage: ai task issue-body [--task <ref> | -t <ref>] [--template <path>]
 
 Print a deterministic Issue body extracted from a task's task.md.
-  Omit <ref>           Resolve the unique active task for the current branch.
-  <ref>               Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope        Resolve the unique active task for the current branch.
+  --task/-t <ref>       Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
   --template <path>   Render the final body for the given GitHub Issue Form (scenario A);
                       without it, print the default '任务输入 + 描述 + 需求' body (scenario B).
 
@@ -71,12 +71,12 @@ function issueBody(args = []) {
         process.exitCode = 1;
         return;
     }
-    if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-        process.stderr.write('ai task issue-body: task ref must be provided once\n');
+    if (scope.positionals.length > 0) {
+        process.stderr.write('ai task issue-body: positional task ref is not supported; use --task <ref> or -t <ref>\n');
         process.exitCode = 1;
         return;
     }
-    const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+    const resolved = resolveTaskContext(scope.taskRef);
     if (!resolved.ok) {
         process.stderr.write(`ai task issue-body: ${resolved.message}\n`);
         process.exitCode = 1;

package/dist/lib/task/commands/log.js

@@ -3,15 +3,15 @@ import { classifyAgent } from '../../agent-clients/tokens.js';
 import { formatTable } from '../../table.js';
 import { parseTaskScope } from '../command-options.js';
 import { resolveTaskContext } from '../resolve-ref.js';
-import { isReviewStage, parseLedger } from '../ledger.js';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, isReviewStage, parseLedgerDocument } from '../ledger.js';
 import { parseActivityLog, pairEntries } from '../activity-log.js';
-const USAGE = `Usage: ai task log [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task log [--task <ref> | -t <ref>]
 
 Renders a task's activity log as a per-step status table. A step's start and
 completion are paired onto one row: STARTED holds the start time, DONE the
 completion time (or '(in progress)' while still running).
-  Omit <ref>   Resolve the unique active task for the current branch.
-  <ref>   Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope   Resolve the unique active task for the current branch.
+  --task/-t <ref> Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 Columns: # (row) / STEP / AGENT / STARTED / DONE / NOTE
   A human-executed step shows AGENT as 'human' and, when it has no start marker,
@@ -85,8 +85,8 @@ function isHumanCountField(field) {
     return fieldNumber(field, 'manual-validation') !== undefined || fieldNumber(field, 'human-decision') !== undefined;
 }
 // A step is human-executed when its agent token is not a known AI token.
-// Known long names (claude-code -> claude, gemini-cli -> gemini) classify as
-// AI; empty or unknown tokens classify as non-AI (human).
+// Known long names classify as AI; empty or unknown tokens classify as non-AI
+// (human).
 export function isHumanAgent(agent) {
     return classifyAgent(agent).status !== 'ai';
 }
@@ -118,12 +118,12 @@ function log(args = []) {
         process.exitCode = 1;
         return;
     }
-    if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-        process.stderr.write('ai task log: task ref must be provided once\n');
+    if (scope.positionals.length > 0) {
+        process.stderr.write('ai task log: positional task ref is not supported; use --task <ref> or -t <ref>\n');
         process.exitCode = 1;
         return;
     }
-    const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+    const resolved = resolveTaskContext(scope.taskRef);
     if (!resolved.ok) {
         process.stderr.write(`ai task log: ${resolved.message}\n`);
         process.exitCode = 1;
@@ -142,7 +142,18 @@ function log(args = []) {
         return;
     }
     const steps = pairEntries(entries);
-    const humanDecisionCounts = countHumanDecisionsByStage(parseLedger(content));
+    let humanDecisionCounts = new Map();
+    let ledgerDiagnostic = null;
+    try {
+        const ledger = parseLedgerDocument(content);
+        if (ledger.present)
+            humanDecisionCounts = countHumanDecisionsByStage(ledger.rows);
+        else
+            ledgerDiagnostic = `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`;
+    }
+    catch (error) {
+        ledgerDiagnostic = `LEDGER_DOCUMENT_INVALID: ${error instanceof Error ? error.message : String(error)}`;
+    }
     const rows = steps.map((s, idx) => {
         const stage = reviewStageForStep(s.step);
         const note = stage
@@ -157,6 +168,10 @@ function log(args = []) {
     for (const line of formatTable(TABLE_HEADERS, rows, { zebra: Boolean(process.stdout.isTTY) })) {
         process.stdout.write(`${line}\n`);
     }
+    if (ledgerDiagnostic) {
+        process.stdout.write(`Ledger: unavailable [${ledgerDiagnostic}]\n`);
+        process.exitCode = 1;
+    }
     process.stdout.write(`Total: ${steps.length} steps\n`);
 }
 export { log };

package/dist/lib/task/commands/show.js

@@ -1,12 +1,11 @@
 import fs from 'node:fs';
 import { parseTaskScope } from '../command-options.js';
 import { resolveTaskContext } from '../resolve-ref.js';
-const USAGE = `Usage: ai task show [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task show [--task <ref> | -t <ref>]
 
 Prints the task.md content for the matching task.
   Omit the ref       Resolve the unique active task for the current branch.
-  N (bare numeric)   Recommended; resolves the active short id via the registry.
-  TASK-YYYYMMDD-HHMMSS  Locates a task in active / blocked / completed / archive.
+  --task/-t <ref>    Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 `;
 function show(args = []) {
     if (args[0] === '--help' || args[0] === '-h') {
@@ -22,12 +21,12 @@ function show(args = []) {
         process.exitCode = 1;
         return;
     }
-    if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-        process.stderr.write('ai task show: task ref must be provided once\n');
+    if (scope.positionals.length > 0) {
+        process.stderr.write('ai task show: positional task ref is not supported; use --task <ref> or -t <ref>\n');
         process.exitCode = 1;
         return;
     }
-    const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+    const resolved = resolveTaskContext(scope.taskRef);
     if (!resolved.ok) {
         process.stderr.write(`ai task show: ${resolved.message}\n`);
         process.exitCode = 1;

package/dist/lib/task/commands/status.js

@@ -8,15 +8,15 @@ import { enumerateArtifacts } from '../artifacts.js';
 import { parseTaskFrontmatter, extractTitle } from '../frontmatter.js';
 import { loadShortIdByTaskId } from '../short-id.js';
 import { getOpenWorkflowWarnings, formatWorkflowWarningSummary } from '../workflow-warnings.js';
-import { parseActivityLog, pairEntries } from '../activity-log.js';
+import { parseActivityLog, pairEntries, startedBackedRows } from '../activity-log.js';
 import { readRun } from '../orchestration.js';
 import { statusCard } from '../../server/display.js';
-const USAGE = `Usage: ai task status [<N | TASK-id> | --task <ref> | -t <ref>]
+const USAGE = `Usage: ai task status [--task <ref> | -t <ref>]
 
 Prints an aggregated "health check" view for a task: header, metadata,
 artifacts, workflow/runtime execution state, and git branch state.
-  Omit <ref>   Resolve the unique active task for the current branch.
-  <ref>   Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  Omit the scope   Resolve the unique active task for the current branch.
+  --task/-t <ref> Bare numeric short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 Git rows are best-effort: a failed git call degrades that row to '-' without
 failing the command.
@@ -155,7 +155,7 @@ function collectWorkflow(content, now = new Date()) {
     if (!parsed.sectionFound || parsed.entries.length === 0) {
         return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
     }
-    const rows = pairEntries(parsed.entries);
+    const rows = startedBackedRows(pairEntries(parsed.entries));
     const latest = rows.at(-1);
     if (!latest) {
         return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
@@ -431,10 +431,10 @@ function status(args = []) {
     let model;
     try {
         const scope = parseTaskScope(args);
-        if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
-            throw new Error('task ref must be provided once');
+        if (scope.positionals.length > 0) {
+            throw new Error('positional task ref is not supported; use --task <ref> or -t <ref>');
         }
-        const resolved = resolveTaskContext(scope.taskRef ?? scope.positionals[0]);
+        const resolved = resolveTaskContext(scope.taskRef);
         if (!resolved.ok)
             throw new Error(resolved.message);
         model = buildFromResolved({