@minionry/minion 0.7.36

package/dist/server/services/plan/front-matter.js

@@ -0,0 +1,43 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { readFileSync, writeFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+export function replaceYamlField(yaml, field, value) {
+    const regex = new RegExp(`^(${field}:\\s*).+$`, 'm');
+    if (regex.test(yaml)) {
+        return yaml.replace(regex, `$1${value}`);
+    }
+    return `${yaml}\n${field}: ${value}`;
+}
+export function replaceFrontMatterField(content, field, value) {
+    const fmMatch = content.match(/^(---\n)([\s\S]*?)(\n---)/);
+    if (!fmMatch)
+        return content;
+    const yaml = replaceYamlField(fmMatch[2], field, value);
+    return `${fmMatch[1]}${yaml}${fmMatch[3]}${content.slice(fmMatch[0].length)}`;
+}
+export function setFrontMatterField(filePath, field, value) {
+    const content = readFileSync(filePath, 'utf-8');
+    const updated = replaceFrontMatterField(content, field, value);
+    writeFileSync(filePath, updated, 'utf-8');
+}
+export async function setFrontMatterFieldAsync(filePath, field, value) {
+    const content = await readFile(filePath, 'utf-8');
+    const updated = replaceFrontMatterField(content, field, value);
+    await writeFile(filePath, updated, 'utf-8');
+}
+export function checkAllAcceptanceCriteria(content) {
+    const sectionStart = content.indexOf('## Acceptance Criteria');
+    if (sectionStart === -1)
+        return content;
+    const afterHeader = content.indexOf('\n', sectionStart);
+    if (afterHeader === -1)
+        return content;
+    const nextSection = content.slice(afterHeader).search(/\n## /);
+    const sectionEnd = nextSection !== -1 ? afterHeader + nextSection : content.length;
+    const before = content.slice(0, afterHeader);
+    const section = content.slice(afterHeader, sectionEnd);
+    const after = content.slice(sectionEnd);
+    const updatedSection = section.replace(/^([-*]\s+)\[ \]/gm, '$1[x]');
+    return before + updatedSection + after;
+}

package/dist/server/services/plan/issue-classification.js

@@ -0,0 +1,10 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export function resolveIsCodeTask(issue) {
+    if (issue.outputType === 'code')
+        return true;
+    if (issue.outputType === 'document')
+        return false;
+    const codeFiles = issue.filesToModify.filter(f => !f.match(/^Output:/i));
+    return codeFiles.length > 0;
+}

package/dist/server/services/plan/issue-effort.js

@@ -0,0 +1,182 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { normalizeSessionHistory, resolveHistoryPaths } from '../../cli/improvisation-history-store.js';
+import { readLatestQualityDeltas, summarizeQualityDelta } from './quality-delta.js';
+import { MAX_REVIEW_ATTEMPTS } from './types.js';
+export function historyReaderFor(workingDir) {
+    return (sessionId) => {
+        const { historyPath } = resolveHistoryPaths(workingDir, sessionId);
+        try {
+            return normalizeSessionHistory(JSON.parse(readFileSync(historyPath, 'utf-8')), sessionId);
+        }
+        catch {
+            return null;
+        }
+    };
+}
+const sessionFactsMemo = new Map();
+export function sessionFactsReaderFor(workingDir) {
+    const readHistory = historyReaderFor(workingDir);
+    return (sessionId) => {
+        const { historyPath } = resolveHistoryPaths(workingDir, sessionId);
+        let stamp;
+        try {
+            const stat = statSync(historyPath);
+            stamp = `${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return {};
+        }
+        const hit = sessionFactsMemo.get(historyPath);
+        if (hit && hit.stamp === stamp)
+            return hit.facts;
+        const facts = sessionFacts(readHistory(sessionId));
+        sessionFactsMemo.set(historyPath, { stamp, facts });
+        return facts;
+    };
+}
+const REVIEW_FILE_RE = /^(.+)-(\d+)\.json$/;
+function toReviewAttempt(record) {
+    const checks = Array.isArray(record.checks) ? record.checks : [];
+    const attempt = {
+        reviewedAt: record.reviewedAt,
+        passed: !!record.passed,
+        failedChecks: checks.filter((c) => !c.passed).map((c) => String(c.name)),
+    };
+    if (typeof record.startedAt === 'string' && typeof record.finishedAt === 'string') {
+        attempt.startedAt = record.startedAt;
+        attempt.finishedAt = record.finishedAt;
+        const durationMs = Date.parse(record.finishedAt) - Date.parse(record.startedAt);
+        if (Number.isFinite(durationMs) && durationMs >= 0)
+            attempt.durationMs = durationMs;
+    }
+    return attempt;
+}
+export function readReviewAttempts(boardDir) {
+    const dir = join(boardDir, 'reviews');
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return new Map();
+    }
+    const files = [];
+    for (const name of names) {
+        const match = name.match(REVIEW_FILE_RE);
+        if (match)
+            files.push({ issueId: match[1], epochMs: Number(match[2]), name });
+    }
+    files.sort((a, b) => a.epochMs - b.epochMs);
+    const attempts = new Map();
+    for (const { issueId, name } of files) {
+        try {
+            const record = JSON.parse(readFileSync(join(dir, name), 'utf-8'));
+            if (!record || typeof record !== 'object' || record.issueId !== issueId)
+                continue;
+            const list = attempts.get(issueId) ?? [];
+            list.push(toReviewAttempt(record));
+            attempts.set(issueId, list);
+        }
+        catch {
+        }
+    }
+    return attempts;
+}
+function dispatchStart(sessionId, issueId) {
+    const prefix = 'improv-';
+    const suffix = `-pm-${issueId}`;
+    if (!sessionId.startsWith(prefix) || !sessionId.endsWith(suffix))
+        return null;
+    const ts = sessionId.slice(prefix.length, sessionId.length - suffix.length);
+    return /^\d+$/.test(ts) ? Number(ts) : null;
+}
+function sumPresent(items, pick) {
+    let sum;
+    for (const item of items) {
+        const value = pick(item);
+        if (value !== undefined)
+            sum = (sum ?? 0) + value;
+    }
+    return sum;
+}
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function sessionFacts(history) {
+    if (!history)
+        return {};
+    const movements = history.movements;
+    const facts = {
+        durationMs: sumPresent(movements, (m) => finite(m.durationMs)),
+        outputTokens: sumPresent(movements, (m) => finite(m.outputTokens)),
+        model: movements.map((m) => m.model).filter(Boolean).at(-1),
+        engine: movements.map((m) => m.engine).filter(Boolean).at(-1) ?? (movements.length > 0 ? history.engine : undefined),
+    };
+    for (const key of Object.keys(facts)) {
+        if (facts[key] === undefined)
+            delete facts[key];
+    }
+    return facts;
+}
+function readDispatches(issue, readFacts) {
+    const dispatches = [];
+    for (const entry of issue.outputHistory) {
+        const startMs = dispatchStart(entry.sessionId, issue.id);
+        if (startMs === null)
+            continue;
+        dispatches.push({
+            startMs,
+            dispatch: {
+                sessionId: entry.sessionId,
+                startedAt: new Date(startMs).toISOString(),
+                status: entry.status,
+                ...readFacts(entry.sessionId),
+            },
+        });
+    }
+    return dispatches.sort((a, b) => a.startMs - b.startMs).map((d) => d.dispatch);
+}
+function deriveIssueEffort(issue, sources) {
+    const dispatches = readDispatches(issue, sources.readFacts);
+    const reviewAttempts = sources.reviewAttempts.get(issue.id) ?? [];
+    if (dispatches.length === 0 && reviewAttempts.length === 0)
+        return null;
+    const models = [];
+    for (const dispatch of dispatches) {
+        if (dispatch.model && !models.includes(dispatch.model))
+            models.push(dispatch.model);
+    }
+    const implementationMs = sumPresent(dispatches, (d) => d.durationMs);
+    const reviewMs = sumPresent(reviewAttempts, (a) => a.durationMs);
+    const outputTokens = sumPresent(dispatches, (d) => d.outputTokens);
+    const delta = sources.qualityDeltas.get(issue.id);
+    return {
+        dispatches,
+        dispatchCount: dispatches.length,
+        reviewAttempts,
+        passedFirstTime: reviewAttempts[0]?.passed === true,
+        cancelledAtCap: issue.status === 'cancelled' && reviewAttempts.length >= MAX_REVIEW_ATTEMPTS,
+        ...(implementationMs !== undefined ? { implementationMs } : {}),
+        ...(reviewMs !== undefined ? { reviewMs } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        models,
+        qualityDelta: delta ? summarizeQualityDelta(delta) : null,
+    };
+}
+export function deriveIssueEfforts(boardDir, issues, readHistory) {
+    return deriveIssueEffortsFromFacts(boardDir, issues, (sessionId) => sessionFacts(readHistory(sessionId)));
+}
+export function deriveIssueEffortsFromFacts(boardDir, issues, readFacts) {
+    const sources = {
+        reviewAttempts: readReviewAttempts(boardDir),
+        qualityDeltas: readLatestQualityDeltas(boardDir),
+        readFacts,
+    };
+    const efforts = new Map();
+    for (const issue of issues)
+        efforts.set(issue.id, deriveIssueEffort(issue, sources));
+    return efforts;
+}

package/dist/server/services/plan/issue-loader.js

@@ -0,0 +1,35 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { activateBoard } from './board-config.js';
+import { NO_SPECS_DIR_ERROR, parseBoardDirectory, parsePlanDirectory } from './parser.js';
+export async function loadBoardIssues(pmDir, boardId, handlers) {
+    const boardState = parseBoardDirectory(pmDir, boardId);
+    if (!boardState) {
+        handlers.onError(`Board not found: ${boardId}`);
+        return null;
+    }
+    if (boardState.state.paused) {
+        handlers.onError('Board is paused');
+        return null;
+    }
+    if (boardState.board.status === 'draft') {
+        await activateBoard(pmDir, boardId, handlers.warn);
+    }
+    else if (boardState.board.status !== 'active') {
+        handlers.onError(`Board ${boardId} is not active (status: ${boardState.board.status})`);
+        return null;
+    }
+    return boardState.issues;
+}
+export function loadProjectIssues(workingDir, handlers) {
+    const fullState = parsePlanDirectory(workingDir);
+    if (!fullState) {
+        handlers.onError(NO_SPECS_DIR_ERROR);
+        return null;
+    }
+    if (fullState.state.paused) {
+        handlers.onError('Project is paused');
+        return null;
+    }
+    return fullState.issues;
+}

package/dist/server/services/plan/issue-prompt-builder.js

@@ -0,0 +1,152 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { join } from 'node:path';
+import { specsDirOrDefault } from '../space-layout.js';
+import { resolveAgentHints } from './agent-resolver.js';
+import { resolveIsCodeTask } from './issue-classification.js';
+const ATTEMPT_TAIL_CHARS = 800;
+const QUALITY_GATE_EFFECT = {
+    off: 'no quality delta is recorded for this issue and the review gate does not see Quality.',
+    advise: 'the review gate sees a Quality delta (the analyzer findings your changes introduce) and the reviewer weighs it; nothing fails on the delta alone.',
+    block: 'the review gate sees a Quality delta (the analyzer findings your changes introduce), and any introduced finding that is critical or high, or in category security, secrets or dependencies, fails the review (check `quality_delta`).',
+};
+export function renderQualityGateSection(issue, gate, isCode) {
+    if (!gate)
+        return '';
+    const lines = ['', '## Quality gate', '', `This board's \`quality_gate\` is **${gate}** — ${QUALITY_GATE_EFFECT[gate]}`];
+    if (gate !== 'off') {
+        if (issue.reviewGate === 'none')
+            lines.push('This issue has `review_gate: none`, so no review reads its delta.');
+        else if (!isCode)
+            lines.push('This is a document issue, so no delta is recorded for it.');
+    }
+    lines.push('', 'The `quality_check_files` tool (MCP server `minionry-quality`) is attached to this session: call it with the working-directory-relative paths you changed to see their active findings (severity, category, path, line, title, suggestion, and whether each is new) before you finish, and fix what it reports where this issue\'s scope allows. It is read-only and persists nothing.');
+    return `\n${lines.join('\n')}`;
+}
+function describeAttemptOutcome(attempt) {
+    switch (attempt.outcome) {
+        case 'completed': return 'the run completed but the issue was not accepted';
+        case 'incomplete': return 'the run ended without finishing the issue';
+        case 'limit': return 'the run stopped on a usage limit';
+        case 'auth': return 'the run stopped on an authentication failure';
+        case 'error': return 'the run failed';
+    }
+}
+export function renderPreviousAttemptSection(attempts) {
+    if (!attempts || attempts.length === 0)
+        return '';
+    const last = attempts[attempts.length - 1];
+    const minutes = Math.max(1, Math.round(last.durationMs / 60_000));
+    const lines = [
+        '',
+        '## Previous attempt',
+        `This issue was dispatched ${attempts.length} time${attempts.length === 1 ? '' : 's'} earlier in this run. The most recent attempt ran ${minutes} min and ${describeAttemptOutcome(last)}.`,
+    ];
+    if (last.error)
+        lines.push(`- Recorded error: ${last.error.slice(0, 300)}`);
+    if (last.toolNames && last.toolNames.length > 0)
+        lines.push(`- Tools it used: ${last.toolNames.slice(0, 20).join(', ')}`);
+    if (last.outFile)
+        lines.push(`- Its output file (may be partial): ${last.outFile}`);
+    if (last.reviewFailures && last.reviewFailures.length > 0) {
+        lines.push('- The review that sent it back failed these checks:');
+        for (const check of last.reviewFailures) {
+            lines.push(`  - ${check.name}: ${check.details.slice(0, 500)}`);
+        }
+    }
+    if (last.tail) {
+        lines.push('', 'The end of its last response (a PRIOR attempt — verify against the files before trusting it):', '```', last.tail.slice(-ATTEMPT_TAIL_CHARS), '```');
+    }
+    lines.push('', 'Do not redo work the previous attempt already completed: read its output file and check the files it changed first, then continue from there. Address every failed review check above explicitly.');
+    return `\n${lines.join('\n')}`;
+}
+function renderAgentsSection(resolved) {
+    if (resolved.length === 0)
+        return '';
+    const matched = resolved.filter(r => r.resolvedName);
+    const unmatched = resolved.filter(r => !r.resolvedName);
+    const lines = ['', '## Suggested Agents'];
+    if (matched.length > 0) {
+        lines.push('Delegate the relevant portions of this work to these subagents using the Task tool (subagent_type = the agent name). Use them as primary executors when the work matches their expertise:');
+        for (const r of matched) {
+            const desc = r.info?.description ? ` — ${r.info.description}` : '';
+            const labelHint = r.hint.toLowerCase() !== (r.resolvedName ?? '').toLowerCase()
+                ? ` (matched from "${r.hint}")`
+                : '';
+            lines.push(`- \`${r.resolvedName}\`${labelHint}${desc}`);
+        }
+    }
+    if (unmatched.length > 0) {
+        lines.push('');
+        lines.push('Role hints with no installed subagent match — use the general-purpose agent (or your best judgment) for work in these areas:');
+        for (const r of unmatched) {
+            lines.push(`- ${r.hint}`);
+        }
+    }
+    return `\n${lines.join('\n')}`;
+}
+export function buildIssuePrompt(options) {
+    const { issue, workingDir, pmDir, boardDir, existingDocs, outputPath } = options;
+    const previousAttemptSection = renderPreviousAttemptSection(options.previousAttempts);
+    const criteria = issue.acceptanceCriteria
+        .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
+        .join('\n');
+    const isCode = resolveIsCodeTask(issue);
+    const codeFiles = isCode ? issue.filesToModify.filter(f => !f.match(/^Output:/i)) : [];
+    const files = codeFiles.length > 0
+        ? `\n## Files to Modify\n${codeFiles.map(f => `- ${f}`).join('\n')}`
+        : '';
+    const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
+    const predecessorSection = predecessorDocs.length > 0
+        ? `\n## Predecessor Outputs\nRead these before starting — they contain context from upstream issues:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
+        : '';
+    const agentSection = renderAgentsSection(resolveAgentHints(issue.agents, workingDir));
+    const qualityGateSection = renderQualityGateSection(issue, options.qualityGate, isCode);
+    const outDir = boardDir ? join(boardDir, 'out') : pmDir ? join(pmDir, 'out') : join(specsDirOrDefault(workingDir), 'out');
+    return `You are executing issue ${issue.id}: ${issue.title}.
+
+## Project Directory
+Working directory: ${workingDir}
+Plan directory: ${pmDir || specsDirOrDefault(workingDir)}
+
+## Issue Specification
+
+**ID**: ${issue.id}
+**Title**: ${issue.title}
+**Type**: ${issue.type} | **Priority**: ${issue.priority} | **Estimate**: ${issue.estimate ?? 'unestimated'}
+
+### Description
+${issue.description}
+
+### Acceptance Criteria
+${criteria || 'No specific criteria defined.'}
+
+### Technical Notes
+${issue.technicalNotes || 'None'}
+${files}${predecessorSection}${agentSection}${previousAttemptSection}${qualityGateSection}
+
+## Your Task
+
+1. Read the full issue spec at ${pmDir ? join(pmDir, issue.path) : issue.path}
+${isCode ? `2. **Implement the code changes** in the source files listed under "Files to Modify". You MUST edit or create the actual source code files — the acceptance criteria describe what the code must do, not what to document. Read each target file first, then make the changes using Edit or Write.
+3. After implementation, write a brief summary of what you changed to **${outputPath}**${predecessorDocs.length > 0 ? ' — this is the handoff artifact for downstream issues' : ''}
+4. After writing output, update the issue front matter: change \`status: in_progress\` to \`status: in_review\`` : `2. Execute all acceptance criteria listed above
+3. Write your output and results to **${outputPath}** — this is the handoff artifact for downstream issues
+4. After writing output, update the issue front matter: change \`status: in_progress\` to \`status: in_review\``}
+
+## Rules
+
+- Stay within this issue's scope. Do not modify files outside your assigned scope.
+- The issue's pointers and claims are a briefing, not ground truth: verify them against the actual code before building on them. If the code contradicts the issue, follow the code and record the discrepancy in your output file.
+- The orchestrator manages STATE.md separately — do not edit STATE.md.
+${isCode ? `- The output file is a summary of work done, NOT a substitute for implementation. You must modify the actual source code files listed in "Files to Modify". A review gate will verify the source files were changed.` : `- Write all significant output to ${outDir}/ so downstream issues can reference it.`}
+- If you cannot complete the issue, leave status as \`in_progress\` and document what blocked you in the output file.`;
+}
+function resolvePredecessorDocs(issue, existingDocs) {
+    return issue.blockedBy
+        .map(bp => {
+        const blockerId = bp.replace(/^backlog\//, '').replace(/\.md$/, '');
+        return existingDocs.find(d => d.toLowerCase().includes(blockerId.toLowerCase()));
+    })
+        .filter(Boolean);
+}

package/dist/server/services/plan/issue-retry.js

@@ -0,0 +1,42 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { appendOutputHistoryEntry } from './issue-writer.js';
+import { createPlanRunner } from './plan-runner-factory.js';
+export async function runIssueWithRetry(config) {
+    const runner = createPlanRunner('issue', {
+        workingDir: config.workingDir,
+        prompt: config.prompt,
+        tabId: config.tabId,
+        engineId: config.engineId,
+        model: config.model,
+        effortLevel: config.effortLevel,
+        fastMode: config.fastMode,
+        stallWarningMs: config.stallWarningMs,
+        stallKillMs: config.stallKillMs,
+        stallHardCapMs: config.stallHardCapMs,
+        stallMaxExtensions: config.stallMaxExtensions,
+        outputCallback: config.outputCallback,
+        thinkingCallback: config.thinkingCallback,
+        toolUseCallback: config.toolUseCallback,
+        tokenUsageCallback: config.tokenUsageCallback,
+        verbose: true,
+        extraEnv: config.extraEnv,
+        abortSignal: config.abortSignal,
+        onRetry: (info) => {
+            config.outputCallback?.(`\n[PM-RETRY] Auto-retry ${info.retryNumber}/${info.maxRetries}: ${info.path} — ${info.reason}\n`);
+        },
+    });
+    const result = await runner.run();
+    if (config.appendHistory) {
+        const { pmDir, issuePath, issueId, issueTitle, execStart } = config.appendHistory;
+        const sessionId = `improv-${execStart}-pm-${issueId}`;
+        const status = result.completed && !result.error ? 'done' : 'failed';
+        await appendOutputHistoryEntry(pmDir, issuePath, {
+            sessionId,
+            title: issueTitle,
+            timestamp: new Date(execStart).toISOString(),
+            status,
+        }, (msg) => { config.outputCallback?.(`\n[PM-HISTORY] ${msg}\n`); });
+    }
+    return result;
+}

package/dist/server/services/plan/issue-writer.js

@@ -0,0 +1,102 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { readFile, writeFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { checkAllAcceptanceCriteria, setFrontMatterFieldAsync } from './front-matter.js';
+const STATUS_LINE_PATTERN = /^status:\s*(\S+)/m;
+export function extractIssueStatus(content) {
+    return content.match(STATUS_LINE_PATTERN)?.[1] ?? null;
+}
+export function validateIssuePath(issuePath, baseDir) {
+    const resolvedBase = resolve(baseDir);
+    const resolvedFull = resolve(resolvedBase, issuePath);
+    const rel = relative(resolvedBase, resolvedFull);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`Invalid issue path: path traversal detected in "${issuePath}"`);
+    }
+    return resolvedFull;
+}
+export async function updateIssueFrontMatter(pmDir, issuePath, newStatus, warn) {
+    try {
+        const fullPath = validateIssuePath(issuePath, pmDir);
+        await setFrontMatterFieldAsync(fullPath, 'status', newStatus);
+        if (newStatus === 'done') {
+            const content = await readFile(fullPath, 'utf-8');
+            const updated = checkAllAcceptanceCriteria(content);
+            if (updated !== content)
+                await writeFile(fullPath, updated, 'utf-8');
+        }
+    }
+    catch (err) {
+        warn(`Warning: failed to update issue front matter for ${issuePath}: ${errMsg(err)}`);
+    }
+}
+export async function revertIncompleteIssues(pmDir, issues, warn) {
+    for (const issue of issues) {
+        const fullPath = validateIssuePath(issue.path, pmDir);
+        try {
+            const content = await readFile(fullPath, 'utf-8');
+            if (extractIssueStatus(content) === 'in_progress') {
+                await updateIssueFrontMatter(pmDir, issue.path, issue.status, warn);
+            }
+        }
+        catch (err) {
+            warn(`Warning: failed to revert issue status: ${errMsg(err)}`, issue.id);
+        }
+    }
+}
+export async function appendCancellationNote(pmDir, issue, reason, warn) {
+    const fullPath = validateIssuePath(issue.path, pmDir);
+    try {
+        let content = await readFile(fullPath, 'utf-8');
+        const entry = `- Cancelled (${new Date().toISOString().split('T')[0]}): ${reason}`;
+        if (content.includes('## Activity')) {
+            content = content.replace(/## Activity/, `## Activity\n${entry}`);
+        }
+        else {
+            content += `\n\n## Activity\n${entry}`;
+        }
+        await writeFile(fullPath, content, 'utf-8');
+    }
+    catch (err) {
+        warn(`Warning: failed to append cancellation note: ${errMsg(err)}`, issue.id);
+    }
+}
+export async function recoverStaleIssues(pmDir, issues, warn) {
+    const staleStatuses = new Set(['in_progress', 'in_review']);
+    const recovered = [];
+    for (const issue of issues) {
+        if (issue.type === 'epic')
+            continue;
+        if (staleStatuses.has(issue.status)) {
+            await updateIssueFrontMatter(pmDir, issue.path, 'todo', warn);
+            recovered.push(`${issue.id} (${issue.status} → todo)`);
+        }
+    }
+    return recovered;
+}
+export async function appendOutputHistoryEntry(pmDir, issuePath, entry, warn) {
+    const fullPath = validateIssuePath(issuePath, pmDir);
+    try {
+        let content = await readFile(fullPath, 'utf-8');
+        const linkText = entry.title ?? entry.sessionId;
+        const line = `- ${entry.timestamp} — [${linkText}](minionry://output/${entry.sessionId}) — ${entry.status}`;
+        if (content.includes('## Output History')) {
+            content = content.replace(/(## Output History\n)([\s\S]*?)(\n## |\s*$)/, (_match, heading, existingBody, tail) => {
+                const body = existingBody.trimEnd();
+                const separator = body.length > 0 ? '\n' : '';
+                return `${heading}${body}${separator}\n${line}\n${tail}`;
+            });
+        }
+        else {
+            content = `${content.trimEnd()}\n\n## Output History\n\n${line}\n`;
+        }
+        await writeFile(fullPath, content, 'utf-8');
+    }
+    catch (err) {
+        warn(`Warning: failed to append output history entry for ${issuePath}: ${errMsg(err)}`);
+    }
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}