@linxin666/dsh-client-ui-task-board 0.3.20 → 0.3.22

package/src/client/panel-mount-core.ts

@@ -20,10 +20,11 @@
  * (shared/client/sidebar-entry-core.ts, synced copy).
  */
 import { createRoot, type Root } from 'react-dom/client'
+import { subscribeBodyInvalidations } from './body-mutations.ts'
 
 /** Options for mountCenterPanel; dsh-ssh mount.tsx and dsh-task-board board-mount.tsx are the canonical consumers. */
 export interface CenterPanelMountOptions {
-  /** Render the panel React tree into a root (initial mount, remount, locale refresh). */
+  /** Render the panel tree (first open, remount while open, locale refresh). */
   render: (root: Root) => void
   /** dataset key of the injected container's view attribute, e.g. `dshSshView` for `data-dsh-ssh-view`. */
   viewDatasetKey: string
@@ -79,31 +80,38 @@ export function mountCenterPanel(options: CenterPanelMountOptions): () => void {
   } catch { /* locale service absent: the panel follows its next natural re-render */ }
 
   const ensure = (): void => {
-    if (container !== undefined) {
-      if (container.isConnected) return
+    if (container !== undefined && !container.isConnected) {
       // The conversation pane was replaced; drop the stale tree and remount.
       root?.unmount()
       root = undefined
       container.remove()
       container = undefined
     }
-    const column = conversationColumn()
-    if (column === undefined) return
-    container = document.createElement('div')
-    container.dataset[options.viewDatasetKey] = ''
-    container.dataset.dshPlugin = options.pluginName
-    container.className = options.viewClassName
-    column.appendChild(container)
+    if (container === undefined) {
+      const column = conversationColumn()
+      if (column === undefined) return
+      container = document.createElement('div')
+      container.dataset[options.viewDatasetKey] = ''
+      container.dataset.dshPlugin = options.pluginName
+      container.className = options.viewClassName
+      column.appendChild(container)
+    }
+    // Keep a visited tree mounted so drafts and terminal sessions survive
+    // close/reopen; an unused panel needs neither a React root nor effects.
+    if (root !== undefined || !options.isOpen()) return
     root = createRoot(container)
     options.render(root)
   }
 
   // The frame mounts after boot settlement; watch for the column's arrival.
-  const waitObserver = new MutationObserver(() => { ensure() })
-  waitObserver.observe(document.body, { childList: true, subtree: true })
+  // The observation is the page-wide hub (shared/client/body-mutations.ts):
+  // every family panel used to hold its own document.body subtree observer, so
+  // the per-mutation cost grew with the number of installed plugins.
+  const unsubscribeBody = subscribeBodyInvalidations(() => { ensure() })
 
   const applyActive = (): void => {
     if (options.isOpen()) {
+      ensure()
       // Single-occupant center column: opening this panel must evict the
       // sibling panel, both its html attribute and its controller state,
       // otherwise the two panels' visibility rules fight and the second
@@ -135,7 +143,7 @@ export function mountCenterPanel(options: CenterPanelMountOptions): () => void {
   return () => {
     document.removeEventListener('click', onClickSidebarRow, true)
     document.removeEventListener(ACTIVATE_EVENT, onOtherActivate)
-    waitObserver.disconnect()
+    unsubscribeBody()
     unsubscribe()
     unsubscribeLocale?.()
     document.documentElement.removeAttribute(options.activeAttribute)

package/src/client/sidebar-entry-core.ts

@@ -14,6 +14,7 @@
  * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
  * edit the shared source and re-run the sync instead of editing a copy.
  */
+import { subscribeBodyInvalidations } from './body-mutations.ts'
 
 /** Per-package configuration for one sidebar entry row. */
 export interface SidebarEntryOptions {
@@ -188,13 +189,15 @@ export function mountSidebarEntry(options: SidebarEntryOptions): () => void {
 
   // Body-level watcher retained as the "whole rebuild" fallback: when the shell
   // tears down the whole sidebar pane, the root observer is gone with it and
-  // only this body observation can notice the new pane mounting. It is no
-  // longer disconnected after placement; the placed-and-still-mounted case
+  // only this body observation can notice the new pane mounting. It stays
+  // subscribed after placement; the placed-and-still-mounted case
   // short-circuits through the cheap document.body.contains(entry) check, so
-  // unrelated app mutations (e.g. chat streaming) cost one contains check
-  // instead of churning the full re-query.
-  const waitObserver = new MutationObserver(() => { tryPlace() })
-  waitObserver.observe(document.body, { childList: true, subtree: true })
+  // unrelated app mutations (e.g. chat streaming) cost one contains check per
+  // frame instead of churning the full re-query. The body observation itself is
+  // the page-wide hub (shared/client/body-mutations.ts): every family plugin
+  // used to hold its own body subtree observer, so the per-mutation cost grew
+  // with the number of installed plugins; the hub keeps exactly one.
+  const unsubscribeBody = subscribeBodyInvalidations(() => { tryPlace() })
 
   // Self-heal: if a React re-render displaces the row, re-insert it in the
   // same frame (microtask before paint -> no visible flicker).
@@ -225,7 +228,7 @@ export function mountSidebarEntry(options: SidebarEntryOptions): () => void {
   tryPlace()
 
   return () => {
-    waitObserver.disconnect()
+    unsubscribeBody()
     rootObserver.disconnect()
     unsubscribeRefresh?.()
     unsubscribeActive?.()

package/src/core/controller.ts

@@ -327,9 +327,8 @@ export class BoardController {
   }
 
   /**
-   * Archive a settled task (done/failed). Running or on-board-unsettled
-   * tasks are refused so the runner keeps exclusive ownership of their
-   * lifecycle.
+   * Archive a task from any status but `running`, whose lifecycle the runner
+   * keeps exclusive ownership of until it settles.
    * @returns true when applied.
    */
   archiveTask(id: string): boolean {

package/src/core/schedule.ts

@@ -179,7 +179,10 @@ function parseField(field: string, min: number, max: number, out: Set<number>):
       high = Number(b)
     } else if (isDigits(range)) {
       low = Number(range)
-      high = Number(range)
+      // Standard cron: a bare value carrying a step runs from that value to the
+      // field maximum (minutes 5/15 are 5,20,35,50), while a bare value alone is
+      // exactly itself (#1493).
+      high = stepRaw === undefined ? low : max
     } else {
       return false
     }

package/src/core/store.ts

@@ -10,7 +10,7 @@
  * localStorage backend.
  */
 import { isValidCron } from './schedule.ts'
-import { isTaskPermission, isTaskStatus, normalizeTargetId, type ScheduleRule, type TaskFreeze, type TaskRecord, type TaskPermission, type TaskStatus } from './tasks.ts'
+import { isTaskPermission, isTaskStatus, normalizeTags, normalizeTargetId, type ScheduleRule, type TaskFreeze, type TaskRecord, type TaskPermission, type TaskStatus } from './tasks.ts'
 import type { TaskHandover } from './handover.ts'
 import { sanitizeFreezeSnapshot } from './freeze-snapshot.ts'
 import { sanitizeHandover } from './handover.ts'
@@ -189,6 +189,10 @@ export function parseLedger(raw: string | null): TaskRecord[] {
     task.reuseSession = row.reuseSession === true ? true : undefined
     task.freeze = normalizeFreeze(row.freeze)
     task.handover = normalizeHandover(row.handover)
+    // Tags are repaired field by field like the schedule: a malformed entry is
+    // dropped, and a list that repairs to nothing clears the field instead of
+    // dropping the task row.
+    task.tags = normalizeTags(row.tags)
     task.permissionConfirmedAt = typeof row.permissionConfirmedAt === 'number' && Number.isFinite(row.permissionConfirmedAt) ? row.permissionConfirmedAt : undefined
     tasks.push(task)
   }

package/src/core/tasks.ts

@@ -94,6 +94,105 @@ export interface TaskFreeze extends FreezeSnapshot {
   frozenBy?: string
 }
 
+/**
+ * One task label (issue #1521). The name is the badge and the tag-filter key;
+ * the optional prompt line rides the execution prompt, so a label may be
+ * display-only (no prefix) or carry an instruction (business-line routing,
+ * output directory, house style) that every run of the task inherits.
+ */
+export interface TaskTag {
+  /** Display name; trimmed, non-empty, unique within the task. */
+  name: string
+  /**
+   * Prompt line injected ahead of the execution prompt. Absent (or blank
+   * after trimming) keeps the tag display-only: it never touches the prompt,
+   * so a label with no prefix has zero execution side effects.
+   */
+  promptPrefix?: string
+}
+
+/** Maximum number of tags carried by one task. */
+export const TASK_TAG_LIMIT = 8
+/** Maximum length of a tag name. */
+export const TAG_NAME_MAX_LENGTH = 32
+/** Maximum length of a tag's injected prompt line. */
+export const TAG_PROMPT_MAX_LENGTH = 200
+
+/** Whether an unknown value is a well-formed tag (strict: the wire gate). */
+export function isTaskTag(value: unknown): value is TaskTag {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const tag = value as Record<string, unknown>
+  if (Object.keys(tag).some(key => key !== 'name' && key !== 'promptPrefix')) return false
+  if (typeof tag.name !== 'string') return false
+  const name = tag.name.trim()
+  if (name === '' || name.length > TAG_NAME_MAX_LENGTH) return false
+  if (tag.promptPrefix !== undefined && typeof tag.promptPrefix !== 'string') return false
+  return tag.promptPrefix === undefined || (tag.promptPrefix as string).trim().length <= TAG_PROMPT_MAX_LENGTH
+}
+
+/**
+ * Whether an unknown value is a well-formed tag list (strict: the wire gate).
+ * An empty list is rejected — clearing tags is expressed by omitting the field
+ * (create) or by an explicit null (update), never by an empty array.
+ */
+export function isTaskTagList(value: unknown): value is TaskTag[] {
+  return Array.isArray(value) && value.length > 0 && value.length <= TASK_TAG_LIMIT && value.every(isTaskTag)
+}
+
+/**
+ * Repair a persisted tag list: keep the well-formed entries, trim, drop
+ * blanks and repeats, cap the count, and collapse a blank prompt line to
+ * "display-only". Returns undefined when nothing usable remains, so the caller
+ * clears the field instead of storing an empty array.
+ */
+export function normalizeTags(value: unknown): TaskTag[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const tags: TaskTag[] = []
+  const seen = new Set<string>()
+  for (const entry of value) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) continue
+    const row = entry as Record<string, unknown>
+    if (typeof row.name !== 'string') continue
+    const name = row.name.trim()
+    if (name === '' || name.length > TAG_NAME_MAX_LENGTH || seen.has(name)) continue
+    const raw = typeof row.promptPrefix === 'string' ? row.promptPrefix.trim() : ''
+    const promptPrefix = raw === '' ? undefined : raw.slice(0, TAG_PROMPT_MAX_LENGTH)
+    seen.add(name)
+    tags.push(promptPrefix === undefined ? { name } : { name, promptPrefix })
+    if (tags.length >= TASK_TAG_LIMIT) break
+  }
+  return tags.length === 0 ? undefined : tags
+}
+
+/**
+ * Stable palette slot (0..5) for a tag name. The same label always lands on the
+ * same tone, so a badge needs no stored colour and two tasks sharing a label
+ * cannot disagree about it.
+ */
+export function tagTone(name: string): number {
+  let hash = 0
+  for (const char of name) hash = (hash * 31 + (char.codePointAt(0) ?? 0)) >>> 0
+  return hash % 6
+}
+
+/**
+ * Union of the labels already carried by `tasks`, first occurrence wins (the
+ * oldest task's hint is the one offered). Feeds the editor's name datalist and
+ * the board's tag filter, so a label defined once can be reused everywhere.
+ */
+export function collectKnownTags(tasks: readonly TaskRecord[]): TaskTag[] {
+  const known: TaskTag[] = []
+  const seen = new Set<string>()
+  for (const task of tasks) {
+    for (const tag of task.tags ?? []) {
+      if (seen.has(tag.name)) continue
+      seen.add(tag.name)
+      known.push(tag)
+    }
+  }
+  return known
+}
+
 /** One task on the board. */
 export interface TaskRecord {
   /** Stable task id (uuid). */
@@ -158,6 +257,12 @@ export interface TaskRecord {
    * bundle's triplet overrides the legacy pin fields at execution time.
    */
   handover?: TaskHandover
+  /**
+   * Task labels (issue #1521): optional, additive, and absent on every task
+   * created before the field existed. A tag whose `promptPrefix` is set is
+   * prepended to the execution prompt; a bare name is display and filter only.
+   */
+  tags?: TaskTag[]
   /**
    * Human confirmation stamp for an above-default effective permission
    * (ms epoch). Absent while the binding awaits confirmation; any permission
@@ -172,8 +277,13 @@ export interface TaskRecord {
   archivedAt?: number
 }
 
-/** Statuses a settled task may be archived from. */
-export const ARCHIVABLE_STATUSES: readonly TaskStatus[] = ['done', 'failed']
+/**
+ * Statuses a task may be archived from: every status but `running`, whose
+ * execution the runner still owns until it settles. A settled-only gate made
+ * the duplicate-and-archive flow a silent no-op for scheduled tasks, which
+ * return to `todo` after every successful run (issue #1447).
+ */
+export const ARCHIVABLE_STATUSES: readonly TaskStatus[] = ['backlog', 'todo', 'done', 'failed']
 
 
 /** Permission presets a task may pin on its execution session (the `/permission <id>` ids). */
@@ -218,6 +328,11 @@ export interface NewTaskInput {
    * sanitized by the protocol gate) attached at creation.
    */
   handover?: TaskHandoverInput
+  /**
+   * Optional task labels. A tag with a non-blank `promptPrefix` is injected
+   * ahead of the execution prompt; a bare name changes nothing at run time.
+   */
+  tags?: TaskTag[]
 }
 
 /** The five kanban columns, in display order. */
@@ -276,6 +391,7 @@ export function freezeOf(
 
 /** Create a task from user input. */
 export function createTask(input: NewTaskInput, now: number, id: string): TaskRecord {
+  const tags = normalizeTags(input.tags)
   return {
     id,
     title: input.title.trim(),
@@ -292,6 +408,7 @@ export function createTask(input: NewTaskInput, now: number, id: string): TaskRe
     reuseSession: input.reuseSession === true ? true : undefined,
     ...(input.freeze === undefined ? {} : { freeze: freezeOf(input.freeze, now) }),
     ...(input.handover === undefined ? {} : { handover: { ...input.handover, bundledAt: now } }),
+    ...(tags === undefined ? {} : { tags }),
   }
 }
 

package/src/core/use-cases/task-archive.ts

@@ -1,6 +1,6 @@
 /**
- * Archive/restore task use case: move a settled (done/failed) task off the
- * main board and back. The task keeps its status, execution history, and
+ * Archive/restore task use case: move a task off the main board and back,
+ * whatever its status but `running`. The task keeps its status, execution history, and
  * transcript references, while archiving disarms any schedule so it cannot
  * create more execution records until the user restores and re-enables it.
  */
@@ -16,10 +16,10 @@ export interface ArchiveTaskResult {
 }
 
 /**
- * Archive one task: only settled statuses (done/failed) can be archived;
- * a running or not-yet-settled task stays on the board (its runner still
- * owns its lifecycle). Archiving disarms a schedule; already-archived tasks
- * are a no-op.
+ * Archive one task: only a `running` task stays on the board (its runner
+ * still owns its lifecycle until the execution settles); every other status
+ * can be archived. Archiving disarms a schedule; already-archived tasks are
+ * a no-op.
  */
 export function applyArchiveTask(
   tasks: readonly TaskRecord[],

package/src/core/use-cases/task-update.ts

@@ -8,7 +8,7 @@
  * back to the runtime default); an unknown permission string is ignored so
  * stale UI can never persist a value the execution service rejects.
  */
-import { freezeOf, isTaskPermission, normalizeTargetId, type TaskRecord, type TaskPermission } from '../tasks.ts'
+import { freezeOf, isTaskPermission, normalizeTags, normalizeTargetId, type TaskRecord, type TaskPermission, type TaskTag } from '../tasks.ts'
 import type { FreezeSnapshot } from '../freeze-snapshot.ts'
 import type { TaskHandoverInput } from '../handover.ts'
 
@@ -20,6 +20,13 @@ export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' |
   freeze?: FreezeSnapshot & { redacted?: boolean } | null
   /** Replaces the handover bundle (restamping bundledAt); an explicit null clears it. */
   handover?: TaskHandoverInput | null
+  /**
+   * Replaces the task's labels (issue #1521). Unlike the content fields, tags
+   * stay editable after the first run: they classify the task and shape the
+   * NEXT execution prompt, they are not the record of what already ran. An
+   * explicit null (or a list that normalizes to nothing) clears them.
+   */
+  tags?: TaskTag[] | null
 }
 
 /** The fields that edit the task's content (what the user reads and what the
@@ -68,7 +75,7 @@ export function applyUpdateTask(
 ): readonly TaskRecord[] {
   return tasks.map(task => {
     if (task.id !== id) return task
-    const { freeze: freezePatch, handover: handoverPatch, ...rest } = patch
+    const { freeze: freezePatch, handover: handoverPatch, tags: tagsPatch, ...rest } = patch
     const workspaceId = 'workspaceId' in patch ? normalizeTargetId(patch.workspaceId) : undefined
     const mode = 'mode' in patch ? normalizeTargetId(patch.mode) : undefined
     const permission = 'permission' in patch ? normalizePermission(task.permission, patch.permission) : undefined
@@ -86,6 +93,9 @@ export function applyUpdateTask(
     next.freeze = freezePatch == null ? undefined : freezeOf(freezePatch, now)
     // Handover follows the same null-clears convention, restamping bundledAt.
     next.handover = handoverPatch == null ? undefined : { ...handoverPatch, bundledAt: now }
+    // Tags use the same convention: a present array replaces the set (after
+    // repair), an explicit null or a fully-invalid list clears it.
+    if ('tags' in patch) next.tags = tagsPatch == null ? undefined : normalizeTags(tagsPatch)
     // The permission confirmation binds the exact permission value: a change
     // of the pinned permission or of the handover bundle re-arms the gate
     // (blocking confirm-then-swap escalation). handover was destructured out

package/src/host-runner.ts

@@ -110,9 +110,15 @@ function escapeProvenanceDelimiter(value: string): string {
 export function promptText(task: TaskRecord): string {
   const body = task.prompt !== '' ? task.prompt : task.title
   const handover = task.handover
-  const preamble = handover === undefined || handover.references.length === 0
+  const handoverPreamble = handover === undefined || handover.references.length === 0
     ? undefined
     : `交接包引用（来自任务看板续接卡片，冻结于 ${new Date(handover.bundledAt).toISOString()}）：\n${handover.references.map(reference => `- ${reference}`).join('\n')}`
+  // Tag prompts come first: they are the run's standing context (business line,
+  // output location), the handover preamble is a per-card note, and the task
+  // body is the instruction itself.
+  const tagPreamble = tagPromptPreamble(task)
+  const preambles = [tagPreamble, handoverPreamble].filter((part): part is string => part !== undefined)
+  const preamble = preambles.length === 0 ? undefined : preambles.join('\n\n')
   const freeze = task.freeze
   if (freeze === undefined) {
     return preamble === undefined ? body : `${preamble}\n\n${body}`
@@ -122,6 +128,23 @@ export function promptText(task: TaskRecord): string {
   return preamble === undefined ? declaration : `${preamble}\n\n${declaration}`
 }
 
+/**
+ * Build the tag section of the execution prompt (issue #1521). Only tags with
+ * a non-blank `promptPrefix` contribute; a task whose tags are all bare names
+ * (or which has no tags at all) yields undefined and the prompt is byte-for-byte
+ * what it was before the feature.
+ */
+function tagPromptPreamble(task: TaskRecord): string | undefined {
+  const lines: string[] = []
+  for (const tag of task.tags ?? []) {
+    const prefix = tag.promptPrefix?.trim()
+    if (prefix === undefined || prefix === '') continue
+    lines.push(`- [${tag.name}] ${escapeProvenanceDelimiter(prefix)}`)
+  }
+  if (lines.length === 0) return undefined
+  return `标签提示（任务看板标签，每次执行前注入）：\n${lines.join('\n')}`
+}
+
 function isErrorTurnEnd(data: unknown): boolean {
   if (typeof data !== 'object' || data === null) return false
   const reason = (data as { reason?: unknown }).reason

package/src/protocol.ts

@@ -1,5 +1,5 @@
 import type { TaskUpdatePatch } from './core/use-cases/task-update.ts'
-import { isTaskPermission, isTaskStatus, type NewTaskInput, type TaskPermission, type TaskRecord, type TaskStatus } from './core/tasks.ts'
+import { isTaskPermission, isTaskStatus, isTaskTagList, type NewTaskInput, type TaskPermission, type TaskRecord, type TaskStatus } from './core/tasks.ts'
 import { parseLedger } from './core/store.ts'
 import { sanitizeFreezeSnapshot, type FreezeSnapshot } from './core/freeze-snapshot.ts'
 import { sanitizeHandover, type TaskHandoverInput } from './core/handover.ts'
@@ -101,6 +101,10 @@ function optionalFiniteNumber(value: unknown): boolean {
 }
 
 function validImportedKnownFields(value: Record<string, unknown>): boolean {
+  // Tags are validated (not repaired) on the import path: an imported task
+  // must carry a well-formed list or none at all, so a hand-edited export
+  // cannot smuggle a malformed tag past the gate.
+  if (value.tags !== undefined && !isTaskTagList(value.tags)) return false
   if (value.schedule !== undefined) {
     const schedule = record(value.schedule)
     if (schedule === undefined || typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
@@ -161,6 +165,7 @@ function importedTask(value: unknown): TaskRecord | undefined {
     ...(task.archivedAt === undefined ? {} : { archivedAt: task.archivedAt }),
     ...(task.freeze === undefined ? {} : { freeze: task.freeze }),
     ...(task.handover === undefined ? {} : { handover: task.handover }),
+    ...(task.tags === undefined ? {} : { tags: task.tags }),
     // 安全门（对抗场景 b）：import 不是人工确认动作，确认戳一律剥除——
     // 高于会话默认权限的绑定经 import 进入后必须重新武装 confirm-permission 门。
   }
@@ -194,11 +199,12 @@ function handoverPayload(value: unknown): TaskHandoverInput | undefined {
 
 function createInput(value: unknown): value is NewTaskInput {
   const input = record(value)
-  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'schedule', 'freeze', 'handover', 'model', 'reuseSession'])) return false
+  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'schedule', 'freeze', 'handover', 'model', 'reuseSession', 'tags'])) return false
   if (typeof input.title !== 'string' || typeof input.description !== 'string' || typeof input.prompt !== 'string') return false
   if (!optionalString(input.workspaceId) || !optionalString(input.mode) || !optionalString(input.model)) return false
   if (input.reuseSession !== undefined && typeof input.reuseSession !== 'boolean') return false
   if (input.permission !== undefined && !isTaskPermission(input.permission)) return false
+  if (input.tags !== undefined && !isTaskTagList(input.tags)) return false
   if (input.freeze !== undefined && freezePayload(input.freeze) === undefined) return false
   if (input.handover !== undefined && handoverPayload(input.handover) === undefined) return false
   if (input.schedule !== undefined) {
@@ -211,13 +217,15 @@ function createInput(value: unknown): value is NewTaskInput {
 
 function updatePatch(value: unknown): boolean {
   const patch = record(value)
-  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'freeze', 'handover', 'model', 'reuseSession'])) return false
+  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'freeze', 'handover', 'model', 'reuseSession', 'tags'])) return false
   // null (or false) clears the reuse opt-in; only a real boolean is accepted.
   if (patch.reuseSession !== undefined && patch.reuseSession !== null && typeof patch.reuseSession !== 'boolean') return false
   for (const key of ['title', 'description', 'prompt', 'workspaceId', 'mode', 'model'] as const) {
     if (!optionalString(patch[key])) return false
   }
   if (patch.permission !== undefined && !isTaskPermission(patch.permission)) return false
+  // null clears the label set; a present array must be a well-formed list.
+  if (patch.tags !== undefined && patch.tags !== null && !isTaskTagList(patch.tags)) return false
   // null clears the snapshot; an object must pass the freeze gate.
   if (patch.freeze !== undefined && patch.freeze !== null && freezePayload(patch.freeze) === undefined) return false
   // Same convention for the handover bundle.