收紧命令校验并保护运行任务删除

Author: javazys

AGENTS.md

@@ -70,6 +70,7 @@ bun run dev -- db check  # 检查数据库完整性与业务统计
 - `maxRetries` 表示首次执行之外允许的重试次数；失败任务按指数退避，耗尽后进入 `dead_letter`，手动重试会重置重试预算。
 - `retryBackoffMs` 和 `timeoutMs` 可按任务覆盖；调度模板克隆时必须保留 `cwd/batchId/maxRetries/retryBackoffMs/timeoutMs`。
 - 运行中任务进入 `cancelled` 后，Worker 必须在轮询周期内终止对应进程树并关闭 run；Gateway 关闭时先按 `shutdownGracePeriodMs` drain，只有剩余任务才重置为 `pending`。
+- 删除任务必须拒绝 `running` 状态、仍有 `running` 执行记录，或仍被 `pending/running/failed/dead_letter` 任务依赖的前置任务；手动删除与过期清理都必须防止子进程失联和依赖悬空。
 - Watchdog 处理数据库中的旧 PID 前必须校验进程命令与配置的 OpenCode 可执行文件匹配；Unix 上仅对确认的独立进程组发送信号。
 - Watchdog 的 `checkIntervalMs` 是心跳检查间隔，`cleanupIntervalMs` 是数据清理间隔，两者不可混用；配置经 `validateConfig` 校验后才允许运行或保存。
 - 调度模板支持 `cron | delayed | recurring`，Scheduler 将模板克隆为普通任务并受 `maxInstances` 限制；`delayed` 成功生成一次后必须自动禁用。
@@ -92,6 +93,7 @@ bun run dev -- db check  # 检查数据库完整性与业务统计
 - Service 层测试直接调用静态方法，不经过 CLI
 - CLI 集成测试通过 `execSync` 子进程执行，并用临时 `SUPERTASK_DB_PATH`，不得读写用户真实数据库
 - `db check/backup/clear/restore` 的交互式 stdout 必须人类可读；非 TTY 或显式 `--json` 必须保持可解析 JSON，成功与错误都要覆盖这三种模式
+- `db check` 报告 `ok=false` 时必须返回非零退出码；CLI 数字参数必须完整匹配整数，不得用 `parseInt` 接受尾随字符或截断小数
 - Gateway 构建产物 E2E 必须使用隔离数据库和假 OpenCode 可执行文件覆盖普通任务、失败重试、`delayed`、`recurring` 和 `cron`，不得为测试调用真实模型
 
 ## 发布流程

README.md

@@ -106,6 +106,7 @@ supertask get --id 1
 supertask status
 supertask cancel --id 1
 supertask retry --id 1
+supertask delete --id 1   # running tasks must be cancelled and fully stopped first
 
 # Scheduled templates (friendly duration format)
 supertask template add --name "Daily" --agent "gen" \
@@ -134,6 +135,8 @@ supertask db check --json
 supertask db check | jq '.counts'
 ```
 
+`db check` exits non-zero when integrity, foreign keys, or required tables fail, while still printing the complete report. CLI IDs and integer options are parsed strictly: values such as `12abc` or `3.5` are rejected instead of being truncated.
+
 ### Duration Format
 
 Schedule supports friendly duration strings:
@@ -188,6 +191,7 @@ Key mechanisms:
 - **Batch isolation** — Same `batchId` serial; different `batchId` parallel
 - **Priority** — `urgency DESC → importance DESC → createdAt ASC → id ASC`
 - **Local Dashboard boundary** — loopback-only listener, same-origin write checks, escaped database output
+- **Guarded deletion** — active runs and prerequisites of executable dependent tasks cannot be deleted
 
 ## Web Dashboard
 
@@ -197,7 +201,7 @@ Health endpoint: `GET http://localhost:4680/health` returns 200 only after Gatew
 
 | Page | Features |
 |------|----------|
-| Task Queue | Filter by status, retry, delete |
+| Task Queue | Filter by status, retry, cancel, guarded delete |
 | Scheduled Tasks | Template CRUD, enable/disable, manual trigger |
 | Execution Logs | task_runs history with session tracking |
 | System Status | Config editor, concurrency monitor, backup-first transactional database clear |
@@ -289,6 +293,7 @@ supertask template add --type cron --cron "0 9 * * *" ...
 - **定时任务** — cron / delayed / recurring，支持友好时间格式
 - **Web 控制台** — 任务监控、执行日志、在线配置、自动备份后事务性清空数据库
 - **Session 追踪** — 自动从 opencode run 输出中捕获 session ID
+- **安全删除** — 活跃执行必须先取消并收敛；仍被可执行任务依赖的前置任务也不会被误删
 
 ### 数据库维护
 
@@ -308,6 +313,8 @@ supertask db check --json
 supertask db check | jq '.counts'
 ```
 
+`db check` 发现完整性、外键或必需表异常时会返回非零退出码，同时保留完整报告。CLI 的 ID 与整数参数采用严格解析，`12abc`、`3.5` 等输入会直接报错，不再截断成另一个合法值。
+
 ### 数据位置
 
 - 数据库：`~/.local/share/opencode/tasks.db`

docs/architecture.md

@@ -93,6 +93,7 @@ pending / running / failed ──cancel──> cancelled
 - 普通失败保存为 `failed`；退避到期后 Worker 可以直接重新抢占。Watchdog 恢复则保存为带 `retryAfter` 的 `pending`。
 - 超出预算进入 `dead_letter`，不会自动执行；手动 retry 将状态改回 `pending`，并把 `retryCount` 清零。
 - 单次任务可覆盖 `maxRetries`、`retryBackoffMs` 和 `timeoutMs`；模板克隆时会复制这些字段。
+- 删除不是运行态迁移：`running` 任务或仍存在 `running` 执行记录的任务必须先取消并等待 Worker 关闭 run；仍被 `pending/running/failed/dead_letter` 任务依赖的前置任务也拒绝删除。手动删除和 Watchdog 过期清理都遵守依赖保护，避免制造悬空任务。
 
 ## 并发、超时与故障恢复
 

docs/operations.md

@@ -51,6 +51,8 @@ supertask db check   # 完整性、外键、业务表和运行状态检查
 
 数据库连接启用 WAL 和 5 秒 `busy_timeout`。每次新连接初始化会自动执行 migrations、启用外键并检查孤立记录；检查失败会拒绝继续运行，不会自动删除用户数据。
 
+CLI 的任务/模板 ID、优先级、重试次数和列表数量均按完整十进制整数解析；带尾随字符、小数、越界值和未知任务状态会返回非零退出码，不会再由 `parseInt` 静默截断。
+
 ## 完整配置
 
 未写出的字段使用下表默认值。Dashboard 保存配置时会进行分组浅合并和完整校验，写入采用临时文件后原子重命名，权限为 `0600`。
@@ -161,6 +163,10 @@ Watchdog 的恢复时间不是任务超时时间。Worker 的 `taskTimeoutMs` 
 
 运行中 `cancel` 会在下一个 Worker 轮询周期被发现，随后终止对应进程树、保留任务 `cancelled` 状态，并把本次 run 关闭为失败。
 
+运行中任务不能直接删除。执行 `supertask cancel --id <id>` 或在 Dashboard 点击“取消”后，还要等待对应 `running` 执行记录关闭；在此之前 CLI 和 Dashboard 删除接口都会返回冲突。这个保护避免任务记录先消失、Worker 无法再定位并终止仍在运行的子进程。
+
+仍被 `pending/running/failed/dead_letter` 任务引用为 `dependsOn` 的前置任务也不能删除；Watchdog 的过期清理遵循同一保护。先处理或删除下游任务，避免制造永远无法满足的悬空依赖。已终态且不可重试的 `done/cancelled` 下游不会阻塞前置任务清理。
+
 ### 配置无法加载
 
 `supertask config` 会输出具体字段错误。修复 `~/.config/opencode/supertask.json` 后重启 Gateway。不要靠删除字段反复试错；先对照上面的范围和两个跨字段约束。
@@ -191,7 +197,7 @@ supertask db backup
 supertask db backup --output ~/supertask-backup/tasks.db
 ```
 
-- `db check` 运行 `PRAGMA integrity_check`、外键检查、必需表检查，并返回三张业务表和运行中记录的数量。
+- `db check` 运行 `PRAGMA integrity_check`、外键检查、必需表检查，并返回三张业务表和运行中记录的数量；检查不通过时仍输出完整报告，但进程退出码为非零，便于监控和 CI 正确判定失败。
 - `db backup` 使用当前连接生成一致性快照，将其转换为不依赖 `-wal`/`-shm` 的独立 SQLite 文件，再用只读连接复检；目标文件已存在时拒绝覆盖。在线备份可以在 Gateway 运行时执行。
 - 自动备份默认与数据库放在同一目录，名称包含用途、UTC 时间和随机后缀，文件权限为 `0600`。
 - `check/backup/clear/restore` 在交互式终端输出人类可读摘要；stdout 非 TTY 时保持 JSON，终端脚本可传 `--json` 强制 JSON。成功和错误使用同一判断，便于 `supertask db check | jq` 等既有调用继续工作。

src/cli/index.ts

@@ -4,7 +4,7 @@ import { TaskTemplateService } from '@core/services/task-template.service';
 import { DatabaseMaintenanceService } from '@core/services/database-maintenance.service';
 import { closeDb } from '@core/db';
 import { parseDuration } from '@core/duration';
-import type { TaskStatus, ScheduleType } from '@core/db/schema';
+import type { ScheduleType } from '@core/db/schema';
 import {
     getPackageVersion,
     restartGatewayAfterMaintenance,
@@ -15,6 +15,11 @@ import {
     renderDatabaseResult,
     type GatewayMaintenanceReport,
 } from './database-output';
+import {
+    parseBoundedInteger,
+    parsePositiveInteger,
+    parseTaskStatus,
+} from './validation';
 
 async function withDb<T>(
     fn: () => Promise<T>,
@@ -113,12 +118,12 @@ program
             prompt: options.prompt,
             model: options.model,
             category: options.category,
-            importance: parseInt(options.importance),
-            urgency: parseInt(options.urgency),
+            importance: parseBoundedInteger(options.importance, 'importance', 1, 5),
+            urgency: parseBoundedInteger(options.urgency, 'urgency', 1, 5),
             batchId: options.batch,
-            dependsOn: options.depends ? parseInt(options.depends) : undefined,
+            dependsOn: options.depends ? parsePositiveInteger(options.depends, 'depends') : undefined,
             cwd: submitCwd,
-            maxRetries: parseInt(options.maxRetries),
+            maxRetries: parseBoundedInteger(options.maxRetries, 'max-retries', 0, 1000),
             retryBackoffMs,
             timeoutMs,
         });
@@ -152,7 +157,7 @@ program
     .description('开始执行任务（标记为 running）')
     .requiredOption('--id <id>', '任务 ID')
     .action(async (options) => withDb(async () => {
-        const task = await TaskService.start(parseInt(options.id), { cwd: process.cwd() });
+        const task = await TaskService.start(parsePositiveInteger(options.id, 'id'), { cwd: process.cwd() });
         if (task) {
             console.log(JSON.stringify({ id: task.id, status: task.status }));
         } else {
@@ -167,7 +172,7 @@ program
     .requiredOption('--id <id>', '任务 ID')
     .option('-l, --log <log>', '结果日志')
     .action(async (options) => withDb(async () => {
-        const task = await TaskService.done(parseInt(options.id), options.log, { cwd: process.cwd() });
+        const task = await TaskService.done(parsePositiveInteger(options.id, 'id'), options.log, { cwd: process.cwd() });
         if (task) {
             console.log(JSON.stringify({ id: task.id, status: task.status }));
         } else {
@@ -182,7 +187,7 @@ program
     .requiredOption('--id <id>', '任务 ID')
     .option('-l, --log <log>', '错误日志')
     .action(async (options) => withDb(async () => {
-        const task = await TaskService.fail(parseInt(options.id), options.log, { cwd: process.cwd() });
+        const task = await TaskService.fail(parsePositiveInteger(options.id, 'id'), options.log, { cwd: process.cwd() });
         if (task) {
             console.log(JSON.stringify({
                 id: task.id,
@@ -200,7 +205,7 @@ program
     .description('取消任务')
     .requiredOption('--id <id>', '任务 ID')
     .action(async (options) => withDb(async () => {
-        const task = await TaskService.cancel(parseInt(options.id), { cwd: process.cwd() });
+        const task = await TaskService.cancel(parsePositiveInteger(options.id, 'id'), { cwd: process.cwd() });
         if (task) {
             console.log(JSON.stringify({ id: task.id, status: task.status }));
         } else {
@@ -216,7 +221,7 @@ program
     .option('-b, --batch <batchId>', '批次 ID（批量重试）')
     .action(async (options) => withDb(async () => {
         if (options.id) {
-            const task = await TaskService.retry(parseInt(options.id), { cwd: process.cwd() });
+            const task = await TaskService.retry(parsePositiveInteger(options.id, 'id'), { cwd: process.cwd() });
             if (task) {
                 console.log(JSON.stringify({ id: task.id, status: task.status }));
             } else {
@@ -250,11 +255,11 @@ program
     .option('-l, --limit <number>', '限制数量', '20')
     .action(async (options) => withDb(async () => {
         const tasks = await TaskService.list({
-            status: options.status as TaskStatus,
+            status: parseTaskStatus(options.status),
             batchId: options.batch,
             category: options.category,
             cwd: process.cwd(),
-            limit: parseInt(options.limit),
+            limit: parsePositiveInteger(options.limit, 'limit'),
         });
         console.log(JSON.stringify(tasks, null, 2));
     }));
@@ -264,7 +269,7 @@ program
     .description('获取单个任务详情')
     .requiredOption('--id <id>', '任务 ID')
     .action(async (options) => withDb(async () => {
-        const task = await TaskService.getById(parseInt(options.id), { cwd: process.cwd() });
+        const task = await TaskService.getById(parsePositiveInteger(options.id, 'id'), { cwd: process.cwd() });
         if (task) {
             console.log(JSON.stringify(task, null, 2));
         } else {
@@ -278,8 +283,9 @@ program
     .description('删除任务')
     .requiredOption('--id <id>', '任务 ID')
     .action(async (options) => withDb(async () => {
-        const deleted = await TaskService.delete(parseInt(options.id), { cwd: process.cwd() });
-        console.log(JSON.stringify({ deleted, id: parseInt(options.id) }));
+        const id = parsePositiveInteger(options.id, 'id');
+        const deleted = await TaskService.delete(id, { cwd: process.cwd() });
+        console.log(JSON.stringify({ deleted, id }));
     }));
 
 program
@@ -336,16 +342,16 @@ program
                     prompt: options.prompt,
                     model: options.model,
                     category: options.category,
-                    importance: parseInt(options.importance),
-                    urgency: parseInt(options.urgency),
+                    importance: parseBoundedInteger(options.importance, 'importance', 1, 5),
+                    urgency: parseBoundedInteger(options.urgency, 'urgency', 1, 5),
                     cwd: process.cwd(),
                     batchId: options.batch,
                     scheduleType: options.type as ScheduleType,
                     cronExpr: options.cron,
                     intervalMs,
                     runAt,
-                    maxInstances: parseInt(options.maxInstances),
-                    maxRetries: parseInt(options.maxRetries),
+                    maxInstances: parseBoundedInteger(options.maxInstances, 'max-instances', 1, 1000),
+                    maxRetries: parseBoundedInteger(options.maxRetries, 'max-retries', 0, 1000),
                     retryBackoffMs,
                     timeoutMs,
                 });
@@ -365,7 +371,7 @@ program
             .description('启用模板')
             .requiredOption('--id <id>', '模板 ID')
             .action(async (options) => withDb(async () => {
-                const tmpl = await TaskTemplateService.enable(parseInt(options.id));
+                const tmpl = await TaskTemplateService.enable(parsePositiveInteger(options.id, 'id'));
                 if (tmpl) {
                     console.log(JSON.stringify({ id: tmpl.id, enabled: true }));
                 } else {
@@ -379,7 +385,7 @@ program
             .description('禁用模板')
             .requiredOption('--id <id>', '模板 ID')
             .action(async (options) => withDb(async () => {
-                const tmpl = await TaskTemplateService.disable(parseInt(options.id));
+                const tmpl = await TaskTemplateService.disable(parsePositiveInteger(options.id, 'id'));
                 if (tmpl) {
                     console.log(JSON.stringify({ id: tmpl.id, enabled: false }));
                 } else {
@@ -393,8 +399,9 @@ program
             .description('删除模板')
             .requiredOption('--id <id>', '模板 ID')
             .action(async (options) => withDb(async () => {
-                const deleted = await TaskTemplateService.delete(parseInt(options.id));
-                console.log(JSON.stringify({ deleted, id: parseInt(options.id) }));
+                const id = parsePositiveInteger(options.id, 'id');
+                const deleted = await TaskTemplateService.delete(id);
+                console.log(JSON.stringify({ deleted, id }));
             })),
     );
 
@@ -408,6 +415,7 @@ databaseCommand
     .action(async (options: { json?: boolean }) => withDb(async () => {
         const result = DatabaseMaintenanceService.check();
         console.log(renderDatabaseResult('check', result, { forceJson: options.json }));
+        if (!result.ok) process.exitCode = 1;
     }, (error) => renderDatabaseError(error, { forceJson: options.json })));
 
 databaseCommand

src/cli/validation.ts

@@ -0,0 +1,43 @@
+import type { TaskStatus } from '@core/db/schema';
+
+const TASK_STATUSES = new Set<TaskStatus>([
+    'pending',
+    'running',
+    'done',
+    'failed',
+    'dead_letter',
+    'cancelled',
+]);
+
+export function parsePositiveInteger(value: string, name: string): number {
+    if (!/^\d+$/.test(value)) throw new Error(`${name} 必须是正整数`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} 必须是正整数`);
+    }
+    return parsed;
+}
+
+export function parseBoundedInteger(
+    value: string,
+    name: string,
+    min: number,
+    max: number,
+): number {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`${name} 必须是 ${min} 到 ${max} 之间的整数`);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+        throw new Error(`${name} 必须是 ${min} 到 ${max} 之间的整数`);
+    }
+    return parsed;
+}
+
+export function parseTaskStatus(value: string | undefined): TaskStatus | undefined {
+    if (value === undefined) return undefined;
+    if (!TASK_STATUSES.has(value as TaskStatus)) {
+        throw new Error(`status 无效：${value}`);
+    }
+    return value as TaskStatus;
+}