dsh-taskboard 0.5.0 → 0.5.2

package/lib/host/sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.js","names":[],"sources":["../../src/host/sdk.ts"],"sourcesContent":["/**\n * Self-contained replacements for the three @deepseek-ai runtime imports the\n * host half used to take from npm-mirror SDK packages (dsh-home-paths,\n * dsh-llm/brand, dsh-tools' defineTool).\n *\n * Why: a published copy must never resolve `@deepseek-ai/dsh-tools` from the\n * profile's node_modules — an npm-mirror dsh-tools there shadows the\n * CLI-internal build for the WHOLE base layer, and the agent loop's private\n * scheduler symbol then misses (`Cannot read properties of undefined\n * (reading 'prepare')` on every tool call). Everything here is a pure,\n * structure-compatible reimplementation of the exact behavior we relied on:\n *\n * - `dshHomePath` mirrors `join(resolve(env.DSH_HOME ?? ~/.dsh), ...segments)`;\n * - `MessageId` is the identity brand the SDK applies at runtime;\n * - `defineTool` compiles our author-facing parameter specs into the same\n *   raw JSON-Schema subset the registry expects (object/properties/required/\n *   additionalProperties/scalars; the `json` node compiles to an\n *   annotation-only schema) and pre-validates model arguments the same way.\n *\n * @module dsh-taskboard/host/sdk\n */\nimport { homedir } from 'node:os'\nimport { join, resolve } from 'node:path'\n\n/** The ledger file's parent: the DSH user home (DSH_HOME overrides). */\nexport function dshHomePath(...segments: string[]): string {\n  const override = process.env.DSH_HOME\n  const home = resolve(override !== undefined && override.length > 0 ? override : join(homedir(), '.dsh'))\n  return join(home, ...segments)\n}\n\n/** Identity brand — runtime no-op, exactly like the SDK's MessageId(). */\nexport function MessageId(id: string): string {\n  return id\n}\n\n/** Author-facing scalar spec. */\ninterface ScalarSpec {\n  readonly type: 'string' | 'number' | 'integer' | 'boolean' | 'null'\n  readonly description?: string\n  readonly enum?: readonly unknown[]\n  readonly const?: unknown\n}\n\n/** Author-facing object spec (additionalProperties is mandatory). */\ninterface ObjectSpec {\n  readonly type: 'object'\n  readonly additionalProperties: boolean\n  readonly description?: string\n  readonly properties?: Readonly<Record<string, ValueSpec>>\n}\n\n/** Author-facing value spec. */\ntype ValueSpec = ScalarSpec | ObjectSpec | { readonly type: 'json' } | { readonly type: 'array'; readonly items?: ValueSpec; readonly description?: string }\n\n/** Author-facing parameter entry (a value spec plus top-level required). */\ntype ParameterSpec = ValueSpec & { readonly required?: boolean }\n\n/** Raw JSON-Schema subset node. */\ntype RawSchema = Record<string, unknown>\n\n/** Compile one value spec to the raw subset (json → annotation-only). */\nfunction compileValue(spec: ValueSpec): RawSchema {\n  const node: RawSchema = {}\n  const description = (spec as { description?: string }).description\n  if (typeof description === 'string' && description.length > 0) node.description = description\n  const type = (spec as { type?: string }).type\n  if (type === undefined || type === 'json') return node\n  if (type === 'object') {\n    const objectSpec = spec as ObjectSpec\n    node.type = 'object'\n    node.additionalProperties = objectSpec.additionalProperties\n    if (objectSpec.properties !== undefined) node.properties = compilePropertyMap(objectSpec.properties).properties\n    return node\n  }\n  if (type === 'array') {\n    node.type = 'array'\n    const items = (spec as { items?: ValueSpec }).items\n    if (items !== undefined) node.items = compileValue(items)\n    return node\n  }\n  node.type = type\n  const enumValues = (spec as ScalarSpec).enum\n  if (enumValues !== undefined) node.enum = [...enumValues]\n  const constValue = (spec as ScalarSpec).const\n  if (constValue !== undefined) node.const = constValue\n  return node\n}\n\n/** Compile a property map: properties + collected required list. */\nfunction compilePropertyMap(spec: Readonly<Record<string, ParameterSpec>>): { properties: Record<string, RawSchema>; required?: string[] } {\n  const properties: Record<string, RawSchema> = {}\n  const required: string[] = []\n  for (const [name, entry] of Object.entries(spec)) {\n    const { required: isRequired, ...valueSpec } = entry as ParameterSpec & Record<string, unknown>\n    properties[name] = compileValue(valueSpec as ValueSpec)\n    if (isRequired === true) required.push(name)\n  }\n  return required.length > 0 ? { properties, required } : { properties }\n}\n\n/** Does a JS value match a raw-subset scalar type? */\nfunction matchesScalarType(value: unknown, type: string): boolean {\n  switch (type) {\n    case 'string': return typeof value === 'string'\n    case 'number': return typeof value === 'number'\n    case 'integer': return typeof value === 'number' && Number.isInteger(value)\n    case 'boolean': return typeof value === 'boolean'\n    case 'null': return value === null\n    default: return true\n  }\n}\n\n/** Validate a value against the compiled subset; returns path-qualified violations. */\nfunction validateValue(schema: RawSchema, value: unknown, path: string): string[] {\n  if (typeof schema.type !== 'string' || schema.type.length === 0) return []\n  if (schema.type === 'object') {\n    if (typeof value !== 'object' || value === null || Array.isArray(value)) return [`${path} must be an object`]\n    const violations: string[] = []\n    const present = value as Record<string, unknown>\n    for (const key of (schema.required as string[] | undefined) ?? []) {\n      if (!(key in present)) violations.push(`${path}.${key} is required`)\n    }\n    if (schema.additionalProperties === false) {\n      const known = new Set(Object.keys((schema.properties as Record<string, RawSchema> | undefined) ?? {}))\n      for (const key of Object.keys(present)) {\n        if (!known.has(key)) violations.push(`${path}.${key} is not a declared property`)\n      }\n    }\n    for (const [key, child] of Object.entries((schema.properties as Record<string, RawSchema> | undefined) ?? {})) {\n      if (key in present) violations.push(...validateValue(child, present[key], `${path}.${key}`))\n    }\n    return violations\n  }\n  if (schema.type === 'array') {\n    if (!Array.isArray(value)) return [`${path} must be an array`]\n    const violations: string[] = []\n    const items = schema.items as RawSchema | undefined\n    if (items !== undefined) {\n      value.forEach((item, index) => { violations.push(...validateValue(items, item, `${path}[${index}]`)) })\n    }\n    return violations\n  }\n  return matchesScalarType(value, schema.type) ? [] : [`${path} must be ${schema.type}`]\n}\n\n/** Options shape we consume (a structural subset of the SDK's defineTool). */\nexport interface DefineToolOptions<A, V> {\n  readonly name: string\n  readonly description: string\n  readonly parameters: Readonly<Record<string, ParameterSpec>>\n  readonly output: {\n    readonly schema: { readonly type: 'json' }\n    render(args: A, value: V): Array<{ type: 'text'; text: string }>\n  }\n  execute(args: A, exec: unknown): Promise<V>\n}\n\n/** A registry-ready tool definition (structure-compatible with the SDK's). */\nexport interface ToolDefinition<A = unknown, V = unknown> {\n  readonly name: string\n  readonly description: string\n  readonly parameters: RawSchema\n  readonly output: {\n    readonly schema: RawSchema\n    render(args: A, value: V): Array<{ type: 'text'; text: string }>\n  }\n  execute(args: A, exec: unknown): Promise<V>\n}\n\n/**\n * Define a first-party tool: compile the parameter spec, pre-validate\n * arguments (message format matches the SDK's ToolArgsError), and pass\n * through the execution.\n */\nexport function defineTool<A extends Record<string, unknown>, V>(options: DefineToolOptions<A, V>): ToolDefinition<A, V> {\n  const compiled = compilePropertyMap(options.parameters as Readonly<Record<string, ParameterSpec>>)\n  const parameters: RawSchema = { type: 'object', properties: compiled.properties }\n  if (compiled.required !== undefined) parameters.required = compiled.required\n  const userExecute = options.execute\n  return {\n    name: options.name,\n    description: options.description,\n    parameters,\n    output: {\n      // The SDK compiles the `json` node to an annotation-only schema.\n      schema: {},\n      render(args, value) {\n        return options.output.render(args, value)\n      },\n    },\n    async execute(args, exec) {\n      const violations = validateValue(parameters, args, 'arguments')\n      if (violations.length > 0) {\n        throw new Error(`Error: invalid arguments: ${violations.join('; ')}`)\n      }\n      return userExecute(args, exec)\n    },\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"sdk.js","names":[],"sources":["../../src/host/sdk.ts"],"sourcesContent":["/**\n * Self-contained replacements for the three @deepseek-ai runtime imports the\n * host half used to take from npm-mirror SDK packages (dsh-home-paths,\n * dsh-llm/brand, dsh-tools' defineTool).\n *\n * Why: a published copy must never resolve `@deepseek-ai/dsh-tools` from the\n * profile's node_modules — an npm-mirror dsh-tools there shadows the\n * CLI-internal build for the WHOLE base layer, and the agent loop's private\n * scheduler symbol then misses (`Cannot read properties of undefined\n * (reading 'prepare')` on every tool call). Everything here is a pure,\n * structure-compatible reimplementation of the exact behavior we relied on:\n *\n * - `dshHomePath` mirrors `join(resolve(env.DSH_HOME ?? ~/.dsh), ...segments)`;\n * - `MessageId` is the identity brand the SDK applies at runtime;\n * - `defineTool` compiles our author-facing parameter specs into the same\n *   raw JSON-Schema subset the registry expects (object/properties/required/\n *   additionalProperties/scalars; the `json` node compiles to an\n *   annotation-only schema) and pre-validates model arguments the same way.\n *\n * @module dsh-taskboard/host/sdk\n */\nimport { homedir } from 'node:os'\nimport { join, resolve } from 'node:path'\n\n/** The ledger file's parent: the DSH user home (DSH_HOME overrides). */\nexport function dshHomePath(...segments: string[]): string {\n  const override = process.env.DSH_HOME\n  const home = resolve(override !== undefined && override.length > 0 ? override : join(homedir(), '.dsh'))\n  return join(home, ...segments)\n}\n\n/** Identity brand — runtime no-op, exactly like the SDK's MessageId(). */\nexport function MessageId(id: string): string {\n  return id\n}\n\n/** Author-facing scalar spec. */\ninterface ScalarSpec {\n  readonly type: 'string' | 'number' | 'integer' | 'boolean' | 'null'\n  readonly description?: string\n  readonly enum?: readonly unknown[]\n  readonly const?: unknown\n}\n\n/** Author-facing object spec (additionalProperties is mandatory). */\ninterface ObjectSpec {\n  readonly type: 'object'\n  readonly additionalProperties: boolean\n  readonly description?: string\n  readonly properties?: Readonly<Record<string, ValueSpec>>\n}\n\n/** Author-facing value spec. */\ntype ValueSpec = ScalarSpec | ObjectSpec | { readonly type: 'json' } | { readonly type: 'array'; readonly items?: ValueSpec; readonly description?: string }\n\n/** Author-facing parameter entry (a value spec plus top-level required). */\ntype ParameterSpec = ValueSpec & { readonly required?: boolean }\n\n/** Raw JSON-Schema subset node. */\ntype RawSchema = Record<string, unknown>\n\n/** Compile one value spec to the raw subset (json → annotation-only). */\nfunction compileValue(spec: ValueSpec): RawSchema {\n  const node: RawSchema = {}\n  const description = (spec as { description?: string }).description\n  if (typeof description === 'string' && description.length > 0) node.description = description\n  const type = (spec as { type?: string }).type\n  if (type === undefined || type === 'json') return node\n  if (type === 'object') {\n    const objectSpec = spec as ObjectSpec\n    node.type = 'object'\n    node.additionalProperties = objectSpec.additionalProperties\n    if (objectSpec.properties !== undefined) node.properties = compilePropertyMap(objectSpec.properties).properties\n    return node\n  }\n  if (type === 'array') {\n    node.type = 'array'\n    const items = (spec as { items?: ValueSpec }).items\n    if (items !== undefined) node.items = compileValue(items)\n    return node\n  }\n  node.type = type\n  const enumValues = (spec as ScalarSpec).enum\n  if (enumValues !== undefined) node.enum = [...enumValues]\n  const constValue = (spec as ScalarSpec).const\n  if (constValue !== undefined) node.const = constValue\n  return node\n}\n\n/** Compile a property map: properties + collected required list. */\nfunction compilePropertyMap(spec: Readonly<Record<string, ParameterSpec>>): { properties: Record<string, RawSchema>; required?: string[] } {\n  const properties: Record<string, RawSchema> = {}\n  const required: string[] = []\n  for (const [name, entry] of Object.entries(spec)) {\n    const { required: isRequired, ...valueSpec } = entry as ParameterSpec & Record<string, unknown>\n    properties[name] = compileValue(valueSpec as ValueSpec)\n    if (isRequired === true) required.push(name)\n  }\n  return required.length > 0 ? { properties, required } : { properties }\n}\n\n/** Does a JS value match a raw-subset scalar type? */\nfunction matchesScalarType(value: unknown, type: string): boolean {\n  switch (type) {\n    case 'string': return typeof value === 'string'\n    case 'number': return typeof value === 'number'\n    case 'integer': return typeof value === 'number' && Number.isInteger(value)\n    case 'boolean': return typeof value === 'boolean'\n    case 'null': return value === null\n    default: return true\n  }\n}\n\n/** Validate a value against the compiled subset; returns path-qualified violations. */\nfunction validateValue(schema: RawSchema, value: unknown, path: string): string[] {\n  if (typeof schema.type !== 'string' || schema.type.length === 0) return []\n  if (schema.type === 'object') {\n    if (typeof value !== 'object' || value === null || Array.isArray(value)) return [`${path} must be an object`]\n    const violations: string[] = []\n    const present = value as Record<string, unknown>\n    for (const key of (schema.required as string[] | undefined) ?? []) {\n      if (!(key in present)) violations.push(`${path}.${key} is required`)\n    }\n    if (schema.additionalProperties === false) {\n      const known = new Set(Object.keys((schema.properties as Record<string, RawSchema> | undefined) ?? {}))\n      for (const key of Object.keys(present)) {\n        if (!known.has(key)) violations.push(`${path}.${key} is not a declared property`)\n      }\n    }\n    for (const [key, child] of Object.entries((schema.properties as Record<string, RawSchema> | undefined) ?? {})) {\n      if (key in present) violations.push(...validateValue(child, present[key], `${path}.${key}`))\n    }\n    return violations\n  }\n  if (schema.type === 'array') {\n    if (!Array.isArray(value)) return [`${path} must be an array`]\n    const violations: string[] = []\n    const items = schema.items as RawSchema | undefined\n    if (items !== undefined) {\n      value.forEach((item, index) => { violations.push(...validateValue(items, item, `${path}[${index}]`)) })\n    }\n    return violations\n  }\n  if (!matchesScalarType(value, schema.type)) return [`${path} must be ${schema.type}`]\n  // T10: enum/const are compiled into the schema — validate them at runtime\n  // too, so the \"pre-validates the same way\" promise holds for every node.\n  const enumValues = schema.enum as unknown[] | undefined\n  if (enumValues !== undefined && !enumValues.some(v => v === value)) {\n    return [`${path} must be one of ${enumValues.map(String).join(', ')}`]\n  }\n  const constValue = (schema as { const?: unknown }).const\n  if (constValue !== undefined && constValue !== value) {\n    return [`${path} must be ${String(constValue)}`]\n  }\n  return []\n}\n\n/** Options shape we consume (a structural subset of the SDK's defineTool). */\nexport interface DefineToolOptions<A, V> {\n  readonly name: string\n  readonly description: string\n  readonly parameters: Readonly<Record<string, ParameterSpec>>\n  readonly output: {\n    readonly schema: { readonly type: 'json' }\n    render(args: A, value: V): Array<{ type: 'text'; text: string }>\n  }\n  execute(args: A, exec: unknown): Promise<V>\n}\n\n/** A registry-ready tool definition (structure-compatible with the SDK's). */\nexport interface ToolDefinition<A = unknown, V = unknown> {\n  readonly name: string\n  readonly description: string\n  readonly parameters: RawSchema\n  readonly output: {\n    readonly schema: RawSchema\n    render(args: A, value: V): Array<{ type: 'text'; text: string }>\n  }\n  execute(args: A, exec: unknown): Promise<V>\n}\n\n/**\n * Define a first-party tool: compile the parameter spec, pre-validate\n * arguments (message format matches the SDK's ToolArgsError), and pass\n * through the execution.\n */\nexport function defineTool<A extends Record<string, unknown>, V>(options: DefineToolOptions<A, V>): ToolDefinition<A, V> {\n  const compiled = compilePropertyMap(options.parameters as Readonly<Record<string, ParameterSpec>>)\n  const parameters: RawSchema = { type: 'object', properties: compiled.properties }\n  if (compiled.required !== undefined) parameters.required = compiled.required\n  const userExecute = options.execute\n  return {\n    name: options.name,\n    description: options.description,\n    parameters,\n    output: {\n      // The SDK compiles the `json` node to an annotation-only schema.\n      schema: {},\n      render(args, value) {\n        return options.output.render(args, value)\n      },\n    },\n    async execute(args, exec) {\n      const violations = validateValue(parameters, args, 'arguments')\n      if (violations.length > 0) {\n        throw new Error(`Error: invalid arguments: ${violations.join('; ')}`)\n      }\n      return userExecute(args, exec)\n    },\n  }\n}\n"],"mappings":"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"}

package/lib/host/store.js

@@ -1,6 +1,6 @@
-import { emptyLedger, pruneExecutions } from "../shared/protocol.js";
+import { emptyLedger, isPlausibleTaskRecord, pruneExecutions } from "../shared/protocol.js";
 import { dirname, join } from "node:path";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, open, readFile, rename } from "node:fs/promises";
 //#region src/host/store.ts
 /**
 * Host-side task ledger: one JSON file under the DSH home, mutated through a
@@ -32,7 +32,17 @@ var TaskStore = class {
 			const raw = await readFile(this.file, "utf8");
 			const parsed = JSON.parse(raw);
 			if (typeof parsed.revision === "number" && Array.isArray(parsed.tasks)) {
-				const tasks = parsed.tasks;
+				const plausible = [];
+				for (const entry of parsed.tasks) {
+					if (!isPlausibleTaskRecord(entry)) {
+						const rawId = entry?.id;
+						const id = typeof rawId === "string" ? rawId.slice(0, 60) : String(rawId);
+						console.warn("[dsh-taskboard] dropping implausible ledger entry on load:", id);
+						continue;
+					}
+					plausible.push(entry);
+				}
+				const tasks = plausible;
 				for (const task of tasks) if (task.status === "in_progress" && task.claimedBy === void 0 && task.updatedBy?.kind === "agent" && typeof task.updatedBy.sessionId === "string") {
 					task.claimedBy = task.updatedBy.sessionId;
 					task.claimedAt = task.updatedAt;
@@ -92,7 +102,7 @@ var TaskStore = class {
 			const draft = structuredClone(this.ledger);
 			const changed = mutator(draft);
 			if (changed === void 0) return {
-				ledger: this.ledger,
+				ledger: deepFreeze(structuredClone(this.ledger)),
 				changed: []
 			};
 			for (const task of changed) pruneExecutions(task);
@@ -109,12 +119,25 @@ var TaskStore = class {
 				fn(change);
 			} catch {}
 			return {
-				ledger: draft,
-				changed
+				ledger: deepFreeze(structuredClone(draft)),
+				changed: changed.map((t) => deepFreeze(structuredClone(t)))
 			};
 		};
 		return this.queue = this.queue.then(run, run);
 	}
+	/**
+	* Run a read INSIDE the serial queue (R3): observes exactly the ledger
+	* state after all previously enqueued mutations — immune to the
+	* write-then-publish window around `mutate`'s persistence. Read-only: the
+	* callback receives a frozen deep clone and nothing is written.
+	*/
+	async read(fn) {
+		const run = async () => {
+			await this.load();
+			return fn(deepFreeze(structuredClone(this.ledger)));
+		};
+		return this.queue = this.queue.then(run, run);
+	}
 };
 /** Recursively freeze a plain-data value (defense in depth for handed-out snapshots). */
 function deepFreeze(value) {
@@ -124,11 +147,21 @@ function deepFreeze(value) {
 	}
 	return value;
 }
-/** Atomic file persist: write temp, then rename over the target. */
+/**
+* Atomic file persist: write temp, fsync, then rename over the target (S10:
+* without the sync, a power loss after rename can leave a zero-length file —
+* the next load would quarantine the ledger and start empty).
+*/
 async function persistAtomic(file, contents) {
 	await mkdir(dirname(file), { recursive: true });
 	const temp = join(dirname(file), `.${Math.random().toString(36).slice(2)}.tmp`);
-	await writeFile(temp, contents, "utf8");
+	const fh = await open(temp, "w");
+	try {
+		await fh.writeFile(contents, "utf8");
+		await fh.sync();
+	} finally {
+		await fh.close();
+	}
 	await rename(temp, file);
 }
 //#endregion

package/lib/host/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","names":[],"sources":["../../src/host/store.ts"],"sourcesContent":["/**\n * Host-side task ledger: one JSON file under the DSH home, mutated through a\n * serial write queue, published as immutable snapshots with a global\n * monotonic revision. Change subscribers (P2: SSE route) observe every\n * committed mutation.\n *\n * @module dsh-taskboard/host/store\n */\nimport { mkdir, readFile, rename, writeFile } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\nimport {\n  LEDGER_SCHEMA_VERSION,\n  emptyLedger,\n  pruneExecutions,\n  type TaskLedger,\n  type TaskRecord,\n} from '../shared/protocol.ts'\n\n/** One committed ledger mutation, handed to change subscribers. */\nexport interface LedgerChange {\n  /** Revision after the mutation. */\n  revision: number\n  /** The mutated tasks, if any (a comment purge may touch none). */\n  tasks: readonly TaskRecord[]\n  /** What kind of mutation this was (for SSE event naming later). */\n  kind: 'task-created' | 'task-updated' | 'task-moved' | 'task-deleted' | 'comment-added' | 'execution-recorded' | 'settings-updated'\n}\n\n/** Options for {@link TaskStore}. */\nexport interface TaskStoreOptions {\n  /** Absolute ledger file path. */\n  file: string\n}\n\n/**\n * The durable ledger. All mutations run through {@link mutate}, which:\n * validates the resulting document, bumps the global revision, persists\n * atomically (temp file + rename), and only then notifies subscribers.\n */\nexport class TaskStore {\n  private readonly file: string\n  private ledger: TaskLedger = emptyLedger()\n  private readonly subscribers = new Set<(change: LedgerChange) => void>()\n  private queue: Promise<unknown> = Promise.resolve()\n  private loaded = false\n\n  /** @param options - file location. */\n  constructor(options: TaskStoreOptions) {\n    this.file = options.file\n  }\n\n  /** Load (once) from disk; a missing file starts empty; a corrupt file is quarantined, not thrown. */\n  async load(): Promise<void> {\n    if (this.loaded) return\n    try {\n      const raw = await readFile(this.file, 'utf8')\n      const parsed = JSON.parse(raw) as TaskLedger\n      if (typeof parsed.revision === 'number' && Array.isArray(parsed.tasks)) {\n        const tasks = parsed.tasks as TaskRecord[]\n        // Migration from pre-claim-field ledgers: an agent-held in_progress\n        // task carried its holder in updatedBy — backfill the explicit claim\n        // fields so the hold survives user edits (updatedBy is audit-only).\n        for (const task of tasks) {\n          if (task.status === 'in_progress' && task.claimedBy === undefined\n            && task.updatedBy?.kind === 'agent' && typeof task.updatedBy.sessionId === 'string') {\n            task.claimedBy = task.updatedBy.sessionId\n            task.claimedAt = task.updatedAt\n          }\n        }\n        this.ledger = { schemaVersion: LEDGER_SCHEMA_VERSION, revision: parsed.revision, tasks }\n      }\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code\n      if (code !== 'ENOENT') {\n        // Quarantine a corrupt ledger: rename it aside, start fresh. Never\n        // take the host down over ledger damage.\n        try {\n          await rename(this.file, `${this.file}.corrupt-${Date.now()}`)\n        } catch { /* best effort */ }\n      }\n    }\n    this.loaded = true\n  }\n\n  /**\n   * The current snapshot — a deep-frozen clone. Mutating the returned value\n   * throws (strict mode) instead of silently bypassing the revision/persist\n   * path; internal state is never handed out.\n   */\n  snapshot(): TaskLedger {\n    return deepFreeze(structuredClone(this.ledger))\n  }\n\n  /** Find a task by id (frozen clone; internal state is never handed out). */\n  get(id: string): TaskRecord | undefined {\n    const task = this.ledger.tasks.find(t => t.id === id)\n    return task === undefined ? undefined : deepFreeze(structuredClone(task))\n  }\n\n  /** Subscribe to committed changes; returns the unsubscribe. */\n  subscribe(fn: (change: LedgerChange) => void): () => void {\n    this.subscribers.add(fn)\n    return () => this.subscribers.delete(fn)\n  }\n\n  /**\n   * Write a timestamped backup copy of the current ledger next to the live\n   * file (import-replace safety, 0.4.0). Never throws the caller's flow —\n   * a backup failure fails the import itself.\n   * @returns the backup file path.\n   */\n  async backup(): Promise<string> {\n    await this.load()\n    const target = `${this.file}.backup-${Date.now()}`\n    await persistAtomic(target, JSON.stringify(this.ledger, null, 2))\n    return target\n  }\n\n  /**\n   * Run one mutation inside the serial queue. The mutator works on a\n   * structured clone; returning `undefined` aborts with no write.\n   * @param kind - change kind for subscribers.\n   * @param mutator - receives the cloned ledger; mutate tasks in place; return the touched tasks.\n   */\n  async mutate(\n    kind: LedgerChange['kind'],\n    mutator: (ledger: TaskLedger) => TaskRecord[] | undefined,\n  ): Promise<{ ledger: TaskLedger; changed: readonly TaskRecord[] }> {\n    const run = async (): Promise<{ ledger: TaskLedger; changed: readonly TaskRecord[] }> => {\n      await this.load()\n      const draft: TaskLedger = structuredClone(this.ledger)\n      const changed = mutator(draft)\n      if (changed === undefined) {\n        return { ledger: this.ledger, changed: [] }\n      }\n      // Retention cap: every committed mutation re-checks the touched tasks,\n      // so execution history can never grow unbounded (SSE state payload).\n      for (const task of changed) pruneExecutions(task)\n      draft.revision += 1\n      const json = JSON.stringify(draft)\n      await persistAtomic(this.file, json)\n      this.ledger = draft\n      const change: LedgerChange = { revision: draft.revision, tasks: changed, kind }\n      for (const fn of this.subscribers) {\n        try {\n          fn(change)\n        } catch { /* subscriber errors never abort the write */ }\n      }\n      return { ledger: draft, changed }\n    }\n    const result = (this.queue = this.queue.then(run, run)) as ReturnType<typeof run>\n    return result\n  }\n}\n\n/** Recursively freeze a plain-data value (defense in depth for handed-out snapshots). */\nfunction deepFreeze<T>(value: T): T {\n  if (value !== null && typeof value === 'object') {\n    if (!Object.isFrozen(value)) Object.freeze(value)\n    for (const key of Object.keys(value as Record<string, unknown>)) {\n      deepFreeze((value as Record<string, unknown>)[key])\n    }\n  }\n  return value\n}\n\n/** Atomic file persist: write temp, then rename over the target. */\nasync function persistAtomic(file: string, contents: string): Promise<void> {\n  await mkdir(dirname(file), { recursive: true })\n  const temp = join(dirname(file), `.${Math.random().toString(36).slice(2)}.tmp`)\n  await writeFile(temp, contents, 'utf8')\n  await rename(temp, file)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAuCA,IAAa,YAAb,MAAuB;CACrB;CACA,SAA6B,YAAY;CACzC,8BAA+B,IAAI,IAAoC;CACvE,QAAkC,QAAQ,QAAQ;CAClD,SAAiB;;CAGjB,YAAY,SAA2B;EACrC,KAAK,OAAO,QAAQ;CACtB;;CAGA,MAAM,OAAsB;EAC1B,IAAI,KAAK,QAAQ;EACjB,IAAI;GACF,MAAM,MAAM,MAAM,SAAS,KAAK,MAAM,MAAM;GAC5C,MAAM,SAAS,KAAK,MAAM,GAAG;GAC7B,IAAI,OAAO,OAAO,aAAa,YAAY,MAAM,QAAQ,OAAO,KAAK,GAAG;IACtE,MAAM,QAAQ,OAAO;IAIrB,KAAK,MAAM,QAAQ,OACjB,IAAI,KAAK,WAAW,iBAAiB,KAAK,cAAc,KAAA,KACnD,KAAK,WAAW,SAAS,WAAW,OAAO,KAAK,UAAU,cAAc,UAAU;KACrF,KAAK,YAAY,KAAK,UAAU;KAChC,KAAK,YAAY,KAAK;IACxB;IAEF,KAAK,SAAS;KAAE,eAAA;KAAsC,UAAU,OAAO;KAAU;IAAM;GACzF;EACF,SAAS,OAAO;GAEd,IADc,MAAgC,SACjC,UAGX,IAAI;IACF,MAAM,OAAO,KAAK,MAAM,GAAG,KAAK,KAAK,WAAW,KAAK,IAAI,GAAG;GAC9D,QAAQ,CAAoB;EAEhC;EACA,KAAK,SAAS;CAChB;;;;;;CAOA,WAAuB;EACrB,OAAO,WAAW,gBAAgB,KAAK,MAAM,CAAC;CAChD;;CAGA,IAAI,IAAoC;EACtC,MAAM,OAAO,KAAK,OAAO,MAAM,MAAK,MAAK,EAAE,OAAO,EAAE;EACpD,OAAO,SAAS,KAAA,IAAY,KAAA,IAAY,WAAW,gBAAgB,IAAI,CAAC;CAC1E;;CAGA,UAAU,IAAgD;EACxD,KAAK,YAAY,IAAI,EAAE;EACvB,aAAa,KAAK,YAAY,OAAO,EAAE;CACzC;;;;;;;CAQA,MAAM,SAA0B;EAC9B,MAAM,KAAK,KAAK;EAChB,MAAM,SAAS,GAAG,KAAK,KAAK,UAAU,KAAK,IAAI;EAC/C,MAAM,cAAc,QAAQ,KAAK,UAAU,KAAK,QAAQ,MAAM,CAAC,CAAC;EAChE,OAAO;CACT;;;;;;;CAQA,MAAM,OACJ,MACA,SACiE;EACjE,MAAM,MAAM,YAA6E;GACvF,MAAM,KAAK,KAAK;GAChB,MAAM,QAAoB,gBAAgB,KAAK,MAAM;GACrD,MAAM,UAAU,QAAQ,KAAK;GAC7B,IAAI,YAAY,KAAA,GACd,OAAO;IAAE,QAAQ,KAAK;IAAQ,SAAS,CAAC;GAAE;GAI5C,KAAK,MAAM,QAAQ,SAAS,gBAAgB,IAAI;GAChD,MAAM,YAAY;GAClB,MAAM,OAAO,KAAK,UAAU,KAAK;GACjC,MAAM,cAAc,KAAK,MAAM,IAAI;GACnC,KAAK,SAAS;GACd,MAAM,SAAuB;IAAE,UAAU,MAAM;IAAU,OAAO;IAAS;GAAK;GAC9E,KAAK,MAAM,MAAM,KAAK,aACpB,IAAI;IACF,GAAG,MAAM;GACX,QAAQ,CAAgD;GAE1D,OAAO;IAAE,QAAQ;IAAO;GAAQ;EAClC;EAEA,OAAO,KADc,QAAQ,KAAK,MAAM,KAAK,KAAK,GAAG;CAEvD;AACF;;AAGA,SAAS,WAAc,OAAa;CAClC,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;EAC/C,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,OAAO,OAAO,KAAK;EAChD,KAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,GAC5D,WAAY,MAAkC,IAAI;CAEtD;CACA,OAAO;AACT;;AAGA,eAAe,cAAc,MAAc,UAAiC;CAC1E,MAAM,MAAM,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;CAC9C,MAAM,OAAO,KAAK,QAAQ,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK;CAC9E,MAAM,UAAU,MAAM,UAAU,MAAM;CACtC,MAAM,OAAO,MAAM,IAAI;AACzB"}
+{"version":3,"file":"store.js","names":[],"sources":["../../src/host/store.ts"],"sourcesContent":["/**\n * Host-side task ledger: one JSON file under the DSH home, mutated through a\n * serial write queue, published as immutable snapshots with a global\n * monotonic revision. Change subscribers (P2: SSE route) observe every\n * committed mutation.\n *\n * @module dsh-taskboard/host/store\n */\nimport { mkdir, open, readFile, rename } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\nimport {\n  LEDGER_SCHEMA_VERSION,\n  emptyLedger,\n  isPlausibleTaskRecord,\n  pruneExecutions,\n  type TaskLedger,\n  type TaskRecord,\n} from '../shared/protocol.ts'\n\n/** One committed ledger mutation, handed to change subscribers. */\nexport interface LedgerChange {\n  /** Revision after the mutation. */\n  revision: number\n  /** The mutated tasks, if any (a comment purge may touch none). */\n  tasks: readonly TaskRecord[]\n  /** What kind of mutation this was (for SSE event naming later). */\n  kind: 'task-created' | 'task-updated' | 'task-moved' | 'task-deleted' | 'comment-added' | 'execution-recorded' | 'settings-updated' | 'ledger-replaced'\n}\n\n/** Options for {@link TaskStore}. */\nexport interface TaskStoreOptions {\n  /** Absolute ledger file path. */\n  file: string\n}\n\n/**\n * The durable ledger. All mutations run through {@link mutate}, which:\n * validates the resulting document, bumps the global revision, persists\n * atomically (temp file + rename), and only then notifies subscribers.\n */\nexport class TaskStore {\n  private readonly file: string\n  private ledger: TaskLedger = emptyLedger()\n  private readonly subscribers = new Set<(change: LedgerChange) => void>()\n  private queue: Promise<unknown> = Promise.resolve()\n  private loaded = false\n\n  /** @param options - file location. */\n  constructor(options: TaskStoreOptions) {\n    this.file = options.file\n  }\n\n  /** Load (once) from disk; a missing file starts empty; a corrupt file is quarantined, not thrown. */\n  async load(): Promise<void> {\n    if (this.loaded) return\n    try {\n      const raw = await readFile(this.file, 'utf8')\n      const parsed = JSON.parse(raw) as TaskLedger\n      if (typeof parsed.revision === 'number' && Array.isArray(parsed.tasks)) {\n        // S11: trust no record wholesale — drop structurally broken entries\n        // (including R4's traversal-shaped ids from a hand-edited file) with\n        // a notice instead of letting them reach the path-building layers.\n        const plausible: TaskRecord[] = []\n        for (const entry of parsed.tasks as unknown[]) {\n          if (!isPlausibleTaskRecord(entry)) {\n            const rawId = (entry as { id?: unknown })?.id\n            const id = typeof rawId === 'string' ? rawId.slice(0, 60) : String(rawId)\n            console.warn('[dsh-taskboard] dropping implausible ledger entry on load:', id)\n            continue\n          }\n          plausible.push(entry as TaskRecord)\n        }\n        const tasks = plausible\n        // Migration from pre-claim-field ledgers: an agent-held in_progress\n        // task carried its holder in updatedBy — backfill the explicit claim\n        // fields so the hold survives user edits (updatedBy is audit-only).\n        for (const task of tasks) {\n          if (task.status === 'in_progress' && task.claimedBy === undefined\n            && task.updatedBy?.kind === 'agent' && typeof task.updatedBy.sessionId === 'string') {\n            task.claimedBy = task.updatedBy.sessionId\n            task.claimedAt = task.updatedAt\n          }\n        }\n        this.ledger = { schemaVersion: LEDGER_SCHEMA_VERSION, revision: parsed.revision, tasks }\n      }\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code\n      if (code !== 'ENOENT') {\n        // Quarantine a corrupt ledger: rename it aside, start fresh. Never\n        // take the host down over ledger damage.\n        try {\n          await rename(this.file, `${this.file}.corrupt-${Date.now()}`)\n        } catch { /* best effort */ }\n      }\n    }\n    this.loaded = true\n  }\n\n  /**\n   * The current snapshot — a deep-frozen clone. Mutating the returned value\n   * throws (strict mode) instead of silently bypassing the revision/persist\n   * path; internal state is never handed out.\n   */\n  snapshot(): TaskLedger {\n    return deepFreeze(structuredClone(this.ledger))\n  }\n\n  /** Find a task by id (frozen clone; internal state is never handed out). */\n  get(id: string): TaskRecord | undefined {\n    const task = this.ledger.tasks.find(t => t.id === id)\n    return task === undefined ? undefined : deepFreeze(structuredClone(task))\n  }\n\n  /** Subscribe to committed changes; returns the unsubscribe. */\n  subscribe(fn: (change: LedgerChange) => void): () => void {\n    this.subscribers.add(fn)\n    return () => this.subscribers.delete(fn)\n  }\n\n  /**\n   * Write a timestamped backup copy of the current ledger next to the live\n   * file (import-replace safety, 0.4.0). Never throws the caller's flow —\n   * a backup failure fails the import itself.\n   * @returns the backup file path.\n   */\n  async backup(): Promise<string> {\n    await this.load()\n    const target = `${this.file}.backup-${Date.now()}`\n    await persistAtomic(target, JSON.stringify(this.ledger, null, 2))\n    return target\n  }\n\n  /**\n   * Run one mutation inside the serial queue. The mutator works on a\n   * structured clone; returning `undefined` aborts with no write.\n   * @param kind - change kind for subscribers.\n   * @param mutator - receives the cloned ledger; mutate tasks in place; return the touched tasks.\n   */\n  async mutate(\n    kind: LedgerChange['kind'],\n    mutator: (ledger: TaskLedger) => TaskRecord[] | undefined,\n  ): Promise<{ ledger: TaskLedger; changed: readonly TaskRecord[] }> {\n    const run = async (): Promise<{ ledger: TaskLedger; changed: readonly TaskRecord[] }> => {\n      await this.load()\n      const draft: TaskLedger = structuredClone(this.ledger)\n      const changed = mutator(draft)\n      if (changed === undefined) {\n        // S9 parity: even a no-op mutation hands out a frozen clone — never\n        // the live internal ledger.\n        return { ledger: deepFreeze(structuredClone(this.ledger)), changed: [] }\n      }\n      // Retention cap: every committed mutation re-checks the touched tasks,\n      // so execution history can never grow unbounded (SSE state payload).\n      for (const task of changed) pruneExecutions(task)\n      draft.revision += 1\n      const json = JSON.stringify(draft)\n      await persistAtomic(this.file, json)\n      this.ledger = draft\n      const change: LedgerChange = { revision: draft.revision, tasks: changed, kind }\n      for (const fn of this.subscribers) {\n        try {\n          fn(change)\n        } catch { /* subscriber errors never abort the write */ }\n      }\n      // S9: hand out frozen clones — the return value used to BE the new\n      // internal ledger; callers must never mutate internal state in place.\n      return {\n        ledger: deepFreeze(structuredClone(draft)),\n        changed: changed.map(t => deepFreeze(structuredClone(t))),\n      }\n    }\n    const result = (this.queue = this.queue.then(run, run)) as ReturnType<typeof run>\n    return result\n  }\n\n  /**\n   * Run a read INSIDE the serial queue (R3): observes exactly the ledger\n   * state after all previously enqueued mutations — immune to the\n   * write-then-publish window around `mutate`'s persistence. Read-only: the\n   * callback receives a frozen deep clone and nothing is written.\n   */\n  async read<T>(fn: (ledger: TaskLedger) => T): Promise<T> {\n    const run = async (): Promise<T> => {\n      await this.load()\n      return fn(deepFreeze(structuredClone(this.ledger)))\n    }\n    const result = (this.queue = this.queue.then(run, run)) as Promise<T>\n    return result\n  }\n}\n\n/** Recursively freeze a plain-data value (defense in depth for handed-out snapshots). */\nfunction deepFreeze<T>(value: T): T {\n  if (value !== null && typeof value === 'object') {\n    if (!Object.isFrozen(value)) Object.freeze(value)\n    for (const key of Object.keys(value as Record<string, unknown>)) {\n      deepFreeze((value as Record<string, unknown>)[key])\n    }\n  }\n  return value\n}\n\n/**\n * Atomic file persist: write temp, fsync, then rename over the target (S10:\n * without the sync, a power loss after rename can leave a zero-length file —\n * the next load would quarantine the ledger and start empty).\n */\nasync function persistAtomic(file: string, contents: string): Promise<void> {\n  await mkdir(dirname(file), { recursive: true })\n  const temp = join(dirname(file), `.${Math.random().toString(36).slice(2)}.tmp`)\n  const fh = await open(temp, 'w')\n  try {\n    await fh.writeFile(contents, 'utf8')\n    await fh.sync()\n  } finally {\n    await fh.close()\n  }\n  await rename(temp, file)\n}\n"],"mappings":"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"}

package/lib/host/templates.js

@@ -106,13 +106,19 @@ var TemplateStore = class {
 		this.templates = parsed;
 		this.loaded = true;
 	}
-	/** Atomic persist (temp + rename), same discipline as the ledger. */
+	/** Atomic persist (temp + fsync + rename — S10, same discipline as the ledger). */
 	async persist(templates) {
-		const { mkdir, writeFile, rename } = await import("node:fs/promises");
+		const { mkdir, open, rename } = await import("node:fs/promises");
 		const { dirname, join } = await import("node:path");
 		await mkdir(dirname(this.file), { recursive: true });
 		const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`);
-		await writeFile(temp, JSON.stringify({ templates }, null, 2), "utf8");
+		const fh = await open(temp, "w");
+		try {
+			await fh.writeFile(JSON.stringify({ templates }, null, 2), "utf8");
+			await fh.sync();
+		} finally {
+			await fh.close();
+		}
 		await rename(temp, this.file);
 	}
 	/** All templates (oldest first). */
@@ -131,6 +137,7 @@ var TemplateStore = class {
 		if (name.length === 0 || name.length > 60) throw new Error("模板名必须 1..60 字符");
 		const now = Date.now();
 		const existing = input.id !== void 0 ? templates.find((t) => t.id === input.id) : void 0;
+		if (existing?.builtin === true) throw new Error("内置模板不可覆盖；可删除后另建，或以新名称存为新模板");
 		const stored = existing !== void 0 ? {
 			...existing,
 			name,

package/lib/host/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","names":[],"sources":["../../src/host/templates.ts"],"sourcesContent":["/**\n * Host-side task-template store (0.4.0): one JSON side file next to the\n * ledger, seeded with the built-in templates on first load, mutated through\n * the same atomic persist discipline as the ledger.\n *\n * Pure data, no Cordis deps — the routes layer owns it and tests drive it\n * directly against a temp dir.\n *\n * @module dsh-taskboard/host/templates\n */\nimport { readFile } from 'node:fs/promises'\nimport type { TaskTemplate } from '../shared/api.ts'\n\n/** The built-in templates seeded when the side file does not exist yet. */\nexport const BUILTIN_TEMPLATES: ReadonlyArray<{ id: string; name: string; task: TaskTemplate['task'] }> = [\n  {\n    id: 'tpl-bugfix',\n    name: 'Bug 修复',\n    task: {\n      title: '修复：',\n      prompt: [\n        '修复以下问题并按序交接：',\n        '1. 复现问题（写最小复现步骤或测试）',\n        '2. 定位根因，说明为什么会发生',\n        '3. 修复并补回归测试',\n        '4. 运行相关测试套件确认无回归',\n      ].join('\\n'),\n      urgency: 'urgent',\n      checklist: ['已复现并定位根因', '修复已提交到任务分支', '回归测试通过'],\n    },\n  },\n  {\n    id: 'tpl-release',\n    name: '发布检查',\n    task: {\n      title: '发布：',\n      prompt: '执行发布流程：版本号更新、构建、测试、变更记录，完成后按序交接（不要实际推送/发布，等用户确认）。',\n      urgency: 'normal',\n      checklist: ['版本号已更新（package.json 与版本常量同步）', '构建通过', '全部测试通过', '变更记录已写'],\n    },\n  },\n  {\n    id: 'tpl-patrol',\n    name: '例行巡检',\n    task: {\n      title: '巡检：',\n      prompt: [\n        '例行巡检：检查依赖更新、失败测试、明显代码问题与未处理的告警。',\n        '发现的问题逐条列出（严重度/位置/建议），小问题直接修复，大问题只报告不动手。',\n        '输出巡检摘要（用 {{lastComments}} 可回看上次巡检结论）。',\n      ].join('\\n'),\n      urgency: 'relaxed',\n      execution: { mode: 'scheduled', cron: '0 9 * * 1' },\n    },\n  },\n]\n\n/** Mint a template id. */\nfunction newTemplateId(): string {\n  return `tpl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`\n}\n\n/**\n * The template store. NOT thread-synchronized like the ledger (template\n * writes are rare, human-paced GUI operations; last-write-wins is fine).\n */\nexport class TemplateStore {\n  private templates: TaskTemplate[] | undefined\n  private loaded = false\n\n  /** @param file - absolute side-file path (next to the ledger). */\n  constructor(private readonly file: string) {}\n\n  /** Load once; a missing file seeds the built-ins; a corrupt file resets. */\n  private async ensure(): Promise<void> {\n    if (this.loaded) return\n    let parsed: TaskTemplate[] | undefined\n    try {\n      const raw = await readFile(this.file, 'utf8')\n      const value = JSON.parse(raw) as { templates?: unknown }\n      if (Array.isArray(value.templates)) {\n        parsed = value.templates.filter((t): t is TaskTemplate =>\n          typeof t === 'object' && t !== null && typeof (t as TaskTemplate).id === 'string'\n          && typeof (t as TaskTemplate).name === 'string' && typeof (t as TaskTemplate).task === 'object')\n      }\n    } catch { /* missing or corrupt → seed */ }\n    if (parsed === undefined) {\n      const now = Date.now()\n      parsed = BUILTIN_TEMPLATES.map((t, i) => ({ ...t, task: { ...t.task }, builtin: true, createdAt: now, updatedAt: now + i }))\n      try { await this.persist(parsed) } catch { /* best effort — the seed returns in-memory */ }\n    }\n    this.templates = parsed\n    this.loaded = true\n  }\n\n  /** Atomic persist (temp + rename), same discipline as the ledger. */\n  private async persist(templates: TaskTemplate[]): Promise<void> {\n    const { mkdir, writeFile, rename } = await import('node:fs/promises')\n    const { dirname, join } = await import('node:path')\n    await mkdir(dirname(this.file), { recursive: true })\n    const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`)\n    await writeFile(temp, JSON.stringify({ templates }, null, 2), 'utf8')\n    await rename(temp, this.file)\n  }\n\n  /** All templates (oldest first). */\n  async list(): Promise<TaskTemplate[]> {\n    await this.ensure()\n    return (this.templates ?? []).slice()\n  }\n\n  /**\n   * Create or replace a template by id (a body without id creates).\n   * @returns the stored template.\n   */\n  async upsert(input: { id?: string; name: string; task: TaskTemplate['task'] }): Promise<TaskTemplate> {\n    await this.ensure()\n    const templates = this.templates ?? []\n    const name = input.name.trim()\n    if (name.length === 0 || name.length > 60) throw new Error('模板名必须 1..60 字符')\n    const now = Date.now()\n    const existing = input.id !== undefined ? templates.find(t => t.id === input.id) : undefined\n    const stored: TaskTemplate = existing !== undefined\n      ? { ...existing, name, task: input.task, updatedAt: now }\n      : { id: input.id ?? newTemplateId(), name, task: input.task, createdAt: now, updatedAt: now }\n    const index = existing !== undefined ? templates.indexOf(existing) : -1\n    if (index >= 0) templates[index] = stored\n    else templates.push(stored)\n    await this.persist(templates)\n    return stored\n  }\n\n  /** Delete a template by id; returns whether it existed. */\n  async remove(id: string): Promise<boolean> {\n    await this.ensure()\n    const templates = this.templates ?? []\n    const index = templates.findIndex(t => t.id === id)\n    if (index < 0) return false\n    templates.splice(index, 1)\n    await this.persist(templates)\n    return true\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"templates.js","names":[],"sources":["../../src/host/templates.ts"],"sourcesContent":["/**\n * Host-side task-template store (0.4.0): one JSON side file next to the\n * ledger, seeded with the built-in templates on first load, mutated through\n * the same atomic persist discipline as the ledger.\n *\n * Pure data, no Cordis deps — the routes layer owns it and tests drive it\n * directly against a temp dir.\n *\n * @module dsh-taskboard/host/templates\n */\nimport { readFile } from 'node:fs/promises'\nimport type { TaskTemplate } from '../shared/api.ts'\n\n/** The built-in templates seeded when the side file does not exist yet. */\nexport const BUILTIN_TEMPLATES: ReadonlyArray<{ id: string; name: string; task: TaskTemplate['task'] }> = [\n  {\n    id: 'tpl-bugfix',\n    name: 'Bug 修复',\n    task: {\n      title: '修复：',\n      prompt: [\n        '修复以下问题并按序交接：',\n        '1. 复现问题（写最小复现步骤或测试）',\n        '2. 定位根因，说明为什么会发生',\n        '3. 修复并补回归测试',\n        '4. 运行相关测试套件确认无回归',\n      ].join('\\n'),\n      urgency: 'urgent',\n      checklist: ['已复现并定位根因', '修复已提交到任务分支', '回归测试通过'],\n    },\n  },\n  {\n    id: 'tpl-release',\n    name: '发布检查',\n    task: {\n      title: '发布：',\n      prompt: '执行发布流程：版本号更新、构建、测试、变更记录，完成后按序交接（不要实际推送/发布，等用户确认）。',\n      urgency: 'normal',\n      checklist: ['版本号已更新（package.json 与版本常量同步）', '构建通过', '全部测试通过', '变更记录已写'],\n    },\n  },\n  {\n    id: 'tpl-patrol',\n    name: '例行巡检',\n    task: {\n      title: '巡检：',\n      prompt: [\n        '例行巡检：检查依赖更新、失败测试、明显代码问题与未处理的告警。',\n        '发现的问题逐条列出（严重度/位置/建议），小问题直接修复，大问题只报告不动手。',\n        '输出巡检摘要（用 {{lastComments}} 可回看上次巡检结论）。',\n      ].join('\\n'),\n      urgency: 'relaxed',\n      execution: { mode: 'scheduled', cron: '0 9 * * 1' },\n    },\n  },\n]\n\n/** Mint a template id. */\nfunction newTemplateId(): string {\n  return `tpl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`\n}\n\n/**\n * The template store. NOT thread-synchronized like the ledger (template\n * writes are rare, human-paced GUI operations; last-write-wins is fine).\n */\nexport class TemplateStore {\n  private templates: TaskTemplate[] | undefined\n  private loaded = false\n\n  /** @param file - absolute side-file path (next to the ledger). */\n  constructor(private readonly file: string) {}\n\n  /** Load once; a missing file seeds the built-ins; a corrupt file resets. */\n  private async ensure(): Promise<void> {\n    if (this.loaded) return\n    let parsed: TaskTemplate[] | undefined\n    try {\n      const raw = await readFile(this.file, 'utf8')\n      const value = JSON.parse(raw) as { templates?: unknown }\n      if (Array.isArray(value.templates)) {\n        parsed = value.templates.filter((t): t is TaskTemplate =>\n          typeof t === 'object' && t !== null && typeof (t as TaskTemplate).id === 'string'\n          && typeof (t as TaskTemplate).name === 'string' && typeof (t as TaskTemplate).task === 'object')\n      }\n    } catch { /* missing or corrupt → seed */ }\n    if (parsed === undefined) {\n      const now = Date.now()\n      parsed = BUILTIN_TEMPLATES.map((t, i) => ({ ...t, task: { ...t.task }, builtin: true, createdAt: now, updatedAt: now + i }))\n      try { await this.persist(parsed) } catch { /* best effort — the seed returns in-memory */ }\n    }\n    this.templates = parsed\n    this.loaded = true\n  }\n\n  /** Atomic persist (temp + fsync + rename — S10, same discipline as the ledger). */\n  private async persist(templates: TaskTemplate[]): Promise<void> {\n    const { mkdir, open, rename } = await import('node:fs/promises')\n    const { dirname, join } = await import('node:path')\n    await mkdir(dirname(this.file), { recursive: true })\n    const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`)\n    const fh = await open(temp, 'w')\n    try {\n      await fh.writeFile(JSON.stringify({ templates }, null, 2), 'utf8')\n      await fh.sync()\n    } finally {\n      await fh.close()\n    }\n    await rename(temp, this.file)\n  }\n\n  /** All templates (oldest first). */\n  async list(): Promise<TaskTemplate[]> {\n    await this.ensure()\n    return (this.templates ?? []).slice()\n  }\n\n  /**\n   * Create or replace a template by id (a body without id creates).\n   * @returns the stored template.\n   */\n  async upsert(input: { id?: string; name: string; task: TaskTemplate['task'] }): Promise<TaskTemplate> {\n    await this.ensure()\n    const templates = this.templates ?? []\n    const name = input.name.trim()\n    if (name.length === 0 || name.length > 60) throw new Error('模板名必须 1..60 字符')\n    const now = Date.now()\n    const existing = input.id !== undefined ? templates.find(t => t.id === input.id) : undefined\n    // T12: built-ins are factory content — editable only by delete + recreate\n    // (deleting stays allowed), never silently overwritten in place.\n    if (existing?.builtin === true) throw new Error('内置模板不可覆盖；可删除后另建，或以新名称存为新模板')\n    const stored: TaskTemplate = existing !== undefined\n      ? { ...existing, name, task: input.task, updatedAt: now }\n      : { id: input.id ?? newTemplateId(), name, task: input.task, createdAt: now, updatedAt: now }\n    const index = existing !== undefined ? templates.indexOf(existing) : -1\n    if (index >= 0) templates[index] = stored\n    else templates.push(stored)\n    await this.persist(templates)\n    return stored\n  }\n\n  /** Delete a template by id; returns whether it existed. */\n  async remove(id: string): Promise<boolean> {\n    await this.ensure()\n    const templates = this.templates ?? []\n    const index = templates.findIndex(t => t.id === id)\n    if (index < 0) return false\n    templates.splice(index, 1)\n    await this.persist(templates)\n    return true\n  }\n}\n"],"mappings":"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"}

package/lib/host/tools.js

@@ -53,7 +53,7 @@ function taskDetail(t) {
 			lines.push(`  - [${e.trigger} ${at}] ${e.outcome}${report}${err}`);
 		}
 	} else lines.push("执行记录: 无");
-	const updatedBy = t.updatedBy.kind === "agent" ? `agent ${String(t.updatedBy.sessionId).slice(0, 24)}` : "user";
+	const updatedBy = t.updatedBy.kind === "agent" ? `agent ${String(t.updatedBy.sessionId).slice(0, 24)}` : t.updatedBy.kind === "system" ? "system" : "user";
 	lines.push(`更新: ${new Date(t.updatedAt).toISOString()} 由 ${updatedBy}`);
 	return lines.join("\n");
 }
@@ -67,7 +67,9 @@ const ERR = {
 	requiresAgent: "unauthorized_actor",
 	invalidInput: "invalid_input"
 };
-/** Tool failure: an Error whose message starts with a stable code. */
+/** Tool failure: an Error whose message starts with a stable code. The code
+*  is also carried structurally so the routes layer can map failures without
+*  re-parsing messages (review P2). */
 var ToolError = class extends Error {
 	code;
 	constructor(code, detail) {
@@ -127,6 +129,22 @@ function versionGuard(task, ifVersion) {
 	if (ifVersion === void 0) throw new ToolError(ERR.versionConflict, "this write requires ifVersion; read the task first");
 	if (ifVersion !== task.version) throw new ToolError(ERR.versionConflict, `stale version ${ifVersion} (current ${task.version}); re-read the task and retry once`);
 }
+/**
+* Find a live (non-trashed) task INSIDE a mutator (R1: every guard must run
+* on the fresh draft the serial queue hands us, never on a pre-read clone —
+* a pre-read can pass its version check and then blind-overwrite a task that
+* changed while the caller awaited). Throws not_found for missing/trashed.
+*/
+function liveTaskAt(ledger, id) {
+	const index = ledger.tasks.findIndex((t) => t.id === id);
+	if (index < 0) throw new ToolError(ERR.notFound, `no task ${id}`);
+	const task = ledger.tasks[index];
+	if (task.trashedAt !== void 0) throw new ToolError(ERR.notFound, `no task ${id}`);
+	return {
+		index,
+		task
+	};
+}
 /** Re-throw with a stable code; non-ToolErrors become invalid_input. */
 function fail(error) {
 	if (error instanceof ToolError) throw error;
@@ -140,7 +158,7 @@ function json(value) {
 	return JSON.parse(JSON.stringify(value));
 }
 /**
-* Register all eight tools.
+* Register all ten tools.
 * @param ctx - a context exposing `tools.register`.
 * @param deps - store + workspaces + clock.
 * @returns dispose functions, one per tool.
@@ -339,12 +357,13 @@ function registerTaskboardTools(ctx, deps) {
 				if (workspaces.get(args.workspaceId) === void 0) throw new ToolError(ERR.notFound, `unknown workspaceId ${args.workspaceId}`);
 				const urgency = asUrgency(args.urgency);
 				const status = args.status === void 0 ? "todo" : asStatus(args.status);
-				if (status === "done" || status === "archived") throw new ToolError(ERR.invalidTransition, "a new task cannot start as done/archived");
+				if (status !== "backlog" && status !== "todo") throw new ToolError(ERR.invalidTransition, "a new task must start as backlog or todo (in_progress requires claiming the task)");
 				const execution = normalizeExecution(args.execution ?? {}, deps.now());
 				const model = args.model !== void 0 ? checkModel(deps, args.model) : void 0;
 				const isolation = args.isolation === void 0 ? defaultIsolationOf(store.snapshot().settings) : asIsolation(args.isolation);
 				const presetId = args.presetId?.trim() || void 0;
-				const checklist = args.checklist !== void 0 ? checklistFromTexts(args.checklist) : void 0;
+				const checklistTexts = args.checklist?.map((c) => c.trim()).filter((c) => c.length > 0);
+				const checklist = checklistTexts !== void 0 && checklistTexts.length > 0 ? checklistFromTexts(checklistTexts) : void 0;
 				const now = deps.now();
 				const task = {
 					id: newTaskId(),
@@ -426,22 +445,21 @@ function registerTaskboardTools(ctx, deps) {
 		async execute(args, exec) {
 			try {
 				const { actor } = caller(exec);
-				const task = store.get(args.id);
-				if (task === void 0 || task.trashedAt !== void 0) throw new ToolError(ERR.notFound, `no task ${args.id}`);
-				versionGuard(task, args.ifVersion);
-				if (task.status === "archived") throw new ToolError(ERR.invalidTransition, "archived tasks are immutable");
-				const next = structuredClone(task);
-				if (args.title !== void 0) next.title = normalizeTitle(args.title);
-				if (args.description !== void 0) next.description = args.description.trim();
-				if (args.prompt !== void 0) next.prompt = normalizePrompt(args.prompt);
-				if (args.urgency !== void 0) next.urgency = asUrgency(args.urgency);
-				if (args.blocked !== void 0) next.blocked = args.blocked;
-				next.version = task.version + 1;
-				next.updatedAt = deps.now();
-				next.updatedBy = actor;
+				let next;
 				await store.mutate("task-updated", (ledger) => {
-					const i = ledger.tasks.findIndex((t) => t.id === args.id);
-					ledger.tasks[i] = next;
+					const { index, task } = liveTaskAt(ledger, args.id);
+					versionGuard(task, args.ifVersion);
+					if (task.status === "archived") throw new ToolError(ERR.invalidTransition, "archived tasks are immutable");
+					next = structuredClone(task);
+					if (args.title !== void 0) next.title = normalizeTitle(args.title);
+					if (args.description !== void 0) next.description = args.description.trim();
+					if (args.prompt !== void 0) next.prompt = normalizePrompt(args.prompt);
+					if (args.urgency !== void 0) next.urgency = asUrgency(args.urgency);
+					if (args.blocked !== void 0) next.blocked = args.blocked;
+					next.version = task.version + 1;
+					next.updatedAt = deps.now();
+					next.updatedBy = actor;
+					ledger.tasks[index] = next;
 					return [next];
 				});
 				return json({ task: summarize(next) });
@@ -484,25 +502,23 @@ function registerTaskboardTools(ctx, deps) {
 			try {
 				const { actor } = caller(exec);
 				const to = asStatus(args.status);
-				const task = store.get(args.id);
-				if (task === void 0 || task.trashedAt !== void 0) throw new ToolError(ERR.notFound, `no task ${args.id}`);
-				versionGuard(task, args.ifVersion);
-				if (to === "done") throw new ToolError(ERR.forbidden, "moving a task to done requires explicit user confirmation (GUI); agents cannot do it");
-				if (!canTransition(task.status, to)) throw new ToolError(ERR.invalidTransition, `illegal transition ${task.status} → ${to}`);
-				if (task.status === "in_progress" && task.claimedBy !== void 0 && task.claimedBy !== actor.sessionId) throw new ToolError(ERR.forbidden, `task is held by session ${task.claimedBy}; never take over another session's claim`);
-				if (isClaim(task.status, to)) {
-					if (await callerWorkspace(deps, exec) !== task.workspaceId) throw new ToolError(ERR.workspaceMismatch, "only a session inside this task's project may claim it");
-				}
-				const next = structuredClone(task);
-				next.status = to;
-				next.version = task.version + 1;
-				next.updatedAt = deps.now();
-				next.updatedBy = actor;
-				if (isClaim(task.status, to)) next.blocked = false;
-				syncClaim(next, to, deps.now(), isClaim(task.status, to) ? actor.sessionId : void 0);
+				const callerWsId = to === "in_progress" ? await callerWorkspace(deps, exec) : void 0;
+				let next;
 				await store.mutate("task-moved", (ledger) => {
-					const i = ledger.tasks.findIndex((t) => t.id === args.id);
-					ledger.tasks[i] = next;
+					const { index, task } = liveTaskAt(ledger, args.id);
+					versionGuard(task, args.ifVersion);
+					if (to === "done") throw new ToolError(ERR.forbidden, "moving a task to done requires explicit user confirmation (GUI); agents cannot do it");
+					if (!canTransition(task.status, to)) throw new ToolError(ERR.invalidTransition, `illegal transition ${task.status} → ${to}`);
+					if (task.status === "in_progress" && task.claimedBy !== void 0 && task.claimedBy !== actor.sessionId) throw new ToolError(ERR.forbidden, `task is held by session ${task.claimedBy}; never take over another session's claim`);
+					if (isClaim(task.status, to) && callerWsId !== task.workspaceId) throw new ToolError(ERR.workspaceMismatch, "only a session inside this task's project may claim it");
+					next = structuredClone(task);
+					next.status = to;
+					next.version = task.version + 1;
+					next.updatedAt = deps.now();
+					next.updatedBy = actor;
+					if (isClaim(task.status, to)) next.blocked = false;
+					syncClaim(next, to, deps.now(), isClaim(task.status, to) ? actor.sessionId : void 0);
+					ledger.tasks[index] = next;
 					return [next];
 				});
 				return json({ task: summarize(next) });
@@ -545,8 +561,6 @@ function registerTaskboardTools(ctx, deps) {
 		async execute(args, exec) {
 			try {
 				const { sessionId } = caller(exec);
-				const task = store.get(args.id);
-				if (task === void 0 || task.trashedAt !== void 0) throw new ToolError(ERR.notFound, `no task ${args.id}`);
 				const comment = {
 					id: newCommentId(),
 					body: normalizeBody(args.body),
@@ -554,13 +568,15 @@ function registerTaskboardTools(ctx, deps) {
 					createdAt: deps.now(),
 					threadId: sessionId
 				};
-				const next = structuredClone(task);
-				next.comments.push(comment);
-				next.version = task.version + 1;
-				next.updatedAt = deps.now();
+				let next;
 				await store.mutate("comment-added", (ledger) => {
-					const i = ledger.tasks.findIndex((t) => t.id === args.id);
-					ledger.tasks[i] = next;
+					const { index, task } = liveTaskAt(ledger, args.id);
+					if (task.status === "archived") throw new ToolError(ERR.invalidTransition, "archived tasks are immutable");
+					next = structuredClone(task);
+					next.comments.push(comment);
+					next.version = task.version + 1;
+					next.updatedAt = deps.now();
+					ledger.tasks[index] = next;
 					return [next];
 				});
 				return json({
@@ -638,15 +654,18 @@ function registerTaskboardTools(ctx, deps) {
 		async execute(args, exec) {
 			try {
 				caller(exec);
-				const task = store.get(args.id);
-				if (task === void 0) throw new ToolError(ERR.notFound, `no task ${args.id}`);
-				versionGuard(task, args.ifVersion);
-				const next = structuredClone(task);
-				next.trashedAt = deps.now();
-				next.version = task.version + 1;
+				let next;
 				await store.mutate("task-deleted", (ledger) => {
-					const i = ledger.tasks.findIndex((t) => t.id === args.id);
-					ledger.tasks[i] = next;
+					const { index, task } = liveTaskAt(ledger, args.id);
+					versionGuard(task, args.ifVersion);
+					if (task.executions.some((e) => e.outcome === "running")) throw new ToolError(ERR.invalidInput, "任务有正在运行的执行（先在 GUI 取消或等它结束再删除）");
+					next = structuredClone(task);
+					next.trashedAt = deps.now();
+					next.version = task.version + 1;
+					delete next.claimedBy;
+					delete next.claimedAt;
+					next.blocked = false;
+					ledger.tasks[index] = next;
 					return [next];
 				});
 				return { trashed: true };
@@ -706,43 +725,42 @@ function registerTaskboardTools(ctx, deps) {
 		async execute(args, exec) {
 			try {
 				const { actor } = caller(exec);
-				const task = store.get(args.id);
-				if (task === void 0 || task.trashedAt !== void 0) throw new ToolError(ERR.notFound, `no task ${args.id}`);
-				versionGuard(task, args.ifVersion);
-				if (task.status === "archived") throw new ToolError(ERR.invalidTransition, "archived tasks are immutable");
-				const next = structuredClone(task);
-				const checklist = next.checklist === void 0 ? [] : [...next.checklist];
-				if (args.action === "add") {
-					const texts = args.items ?? [];
-					if (texts.length === 0 || texts.length > 10) throw new ToolError(ERR.invalidInput, "items must carry 1..10 texts per add call");
-					if (checklist.length + texts.length > 30) throw new ToolError(ERR.invalidInput, `checklist may hold at most 30 items (currently ${checklist.length})`);
-					checklist.push(...checklistFromTexts(texts));
-				} else if (args.action === "check") {
-					if (args.itemId === void 0) throw new ToolError(ERR.invalidInput, "itemId is required for check");
-					const item = checklist.find((i) => i.id === args.itemId);
-					if (item === void 0) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`);
-					const note = args.note !== void 0 && args.note.trim().length > 0 ? args.note.trim().slice(0, 400) : void 0;
-					item.checked = true;
-					item.checkedBy = actor.sessionId;
-					item.checkedAt = deps.now();
-					if (note !== void 0) item.note = note;
-				} else if (args.action === "uncheck") {
-					if (args.itemId === void 0) throw new ToolError(ERR.invalidInput, "itemId is required for uncheck");
-					const item = checklist.find((i) => i.id === args.itemId);
-					if (item === void 0) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`);
-					item.checked = false;
-					delete item.checkedBy;
-					delete item.checkedAt;
-					delete item.note;
-				} else throw new ToolError(ERR.invalidInput, `action must be add | check | uncheck (got "${args.action}")`);
-				if (checklist.length > 0) next.checklist = checklist;
-				else delete next.checklist;
-				next.version = task.version + 1;
-				next.updatedAt = deps.now();
-				next.updatedBy = actor;
+				let next;
 				await store.mutate("task-updated", (ledger) => {
-					const i = ledger.tasks.findIndex((t) => t.id === args.id);
-					ledger.tasks[i] = next;
+					const { index, task } = liveTaskAt(ledger, args.id);
+					versionGuard(task, args.ifVersion);
+					if (task.status === "archived") throw new ToolError(ERR.invalidTransition, "archived tasks are immutable");
+					next = structuredClone(task);
+					const checklist = next.checklist === void 0 ? [] : [...next.checklist];
+					if (args.action === "add") {
+						const texts = args.items ?? [];
+						if (texts.length === 0 || texts.length > 10) throw new ToolError(ERR.invalidInput, "items must carry 1..10 texts per add call");
+						if (checklist.length + texts.length > 30) throw new ToolError(ERR.invalidInput, `checklist may hold at most 30 items (currently ${checklist.length})`);
+						checklist.push(...checklistFromTexts(texts));
+					} else if (args.action === "check") {
+						if (args.itemId === void 0) throw new ToolError(ERR.invalidInput, "itemId is required for check");
+						const item = checklist.find((i) => i.id === args.itemId);
+						if (item === void 0) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`);
+						const note = args.note !== void 0 && args.note.trim().length > 0 ? args.note.trim().slice(0, 400) : void 0;
+						item.checked = true;
+						item.checkedBy = actor.sessionId;
+						item.checkedAt = deps.now();
+						if (note !== void 0) item.note = note;
+					} else if (args.action === "uncheck") {
+						if (args.itemId === void 0) throw new ToolError(ERR.invalidInput, "itemId is required for uncheck");
+						const item = checklist.find((i) => i.id === args.itemId);
+						if (item === void 0) throw new ToolError(ERR.notFound, `no checklist item ${args.itemId} (task ${args.id})`);
+						item.checked = false;
+						delete item.checkedBy;
+						delete item.checkedAt;
+						delete item.note;
+					} else throw new ToolError(ERR.invalidInput, `action must be add | check | uncheck (got "${args.action}")`);
+					if (checklist.length > 0) next.checklist = checklist;
+					else delete next.checklist;
+					next.version = task.version + 1;
+					next.updatedAt = deps.now();
+					next.updatedBy = actor;
+					ledger.tasks[index] = next;
 					return [next];
 				});
 				const progress = next.checklist !== void 0 ? {
@@ -767,7 +785,7 @@ function registerTaskboardTools(ctx, deps) {
 	})));
 	disposers.push(register(defineTool({
 		name: "taskboard_execution_report",
-		description: "Submit the structured execution report for the task you are currently executing (summary / changed files / how you verified / artifacts / remaining risk). Submit BEFORE moving the task to in_review; a later submission overwrites the previous report. Commits and diffs are host-collected — do not repeat them.",
+		description: "Submit the structured execution report for the task you are currently executing (summary / changed files / how you verified / artifacts / remaining risk). Submit BEFORE moving the task to in_review; a later submission overwrites the previous report. If your run already settled, you may back-submit onto your latest succeeded execution while you still hold the task. Commits and diffs are host-collected.",
 		parameters: {
 			summary: {
 				type: "string",
@@ -825,7 +843,20 @@ function registerTaskboardTools(ctx, deps) {
 						}
 					}
 				});
-				if (taskId === void 0 || executionId === void 0) throw new ToolError(ERR.forbidden, "no running execution belongs to this session — the report can only be submitted while the taskboard execution session is still running");
+				if (taskId === void 0 || executionId === void 0) await store.mutate("execution-recorded", (ledger) => {
+					for (const task of ledger.tasks) {
+						if (task.trashedAt !== void 0 || task.status === "archived") continue;
+						const last = task.executions[task.executions.length - 1];
+						const owned = last !== void 0 && last.sessionId === sessionId && last.outcome === "succeeded";
+						const holds = task.claimedBy === sessionId && last !== void 0 && last.sessionId === sessionId;
+						if (!owned && !holds) continue;
+						last.report = report;
+						taskId = task.id;
+						executionId = last.id;
+						return [task];
+					}
+				});
+				if (taskId === void 0 || executionId === void 0) throw new ToolError(ERR.forbidden, "no running execution and no settled execution of yours to report on — reports attach to your running execution, or back-submit onto your latest succeeded one while you hold the task");
 				return json({
 					taskId,
 					executionId,
@@ -839,6 +870,6 @@ function registerTaskboardTools(ctx, deps) {
 	return disposers;
 }
 //#endregion
-export { ERR, registerTaskboardTools, workspaceFace };
+export { ERR, ToolError, registerTaskboardTools, workspaceFace };
 
 //# sourceMappingURL=tools.js.map