dsh-brief-sidebar 0.3.0

package/src/client/file-open.ts

@@ -0,0 +1,108 @@
+/**
+ * Opening a produced file's preview in the right Sidebar — the same channel
+ * the conversation flow uses for its produced-file chips and inline mentions
+ * (ui-chat `openFile` → `ctx.sidebarRight.openResource` with a
+ * `dsh-resource://file/…` address).
+ *
+ * The address grammar is ported verbatim from the harness's browser-safe
+ * `@deepseek-ai/dsh-util-workspace-path` (`file-address.ts` / `index.ts`),
+ * because the plugin does not compile against that package: a relative path,
+ * or an absolute path inside the session's workspace, is addressed under the
+ * session's scope (`dsh-resource://file/session/<id>/<path>`); an absolute
+ * path elsewhere keeps its absolute spelling in the same session's address.
+ * Which tab type claims the address is the Sidebar's decision, not ours.
+ *
+ * The `sidebarRight` service is consumed structurally and treated as OPTIONAL:
+ * where it is absent the section renders plain rows instead of links, the same
+ * graceful degradation as the deliverables projection itself.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Structural view of the right-Sidebar service this plugin needs. */
+export interface SidebarRightLike {
+  openResource(url: string, options?: { params?: { line?: number } }): void
+}
+
+/** Structural view of the sessions service slice the opener reads. */
+interface SessionsListLike {
+  list?: { getSnapshot(): { byId?: Record<string, { cwd?: string }> } }
+}
+
+/** The address scheme every file resource opens with. */
+const FILE_ADDRESS_PREFIX = 'dsh-resource://file/'
+
+/** Whether a path uses a Windows drive or UNC prefix. */
+function isWindowsStylePath(value: string): boolean {
+  return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith('\\\\')
+}
+
+/**
+ * Whether a path is absolute in either spelling the Host accepts: POSIX (`/a/b`)
+ * or Windows drive or UNC.
+ */
+export function isAbsoluteWorkspacePath(path: string): boolean {
+  return path.startsWith('/') || isWindowsStylePath(path)
+}
+
+/** Component-encode one id or path segment, keeping `:` literal for drive letters. */
+function encodeSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/%3A/gi, ':')
+}
+
+/** Encode a `/`-separated path segment by segment. */
+function encodePath(path: string): string {
+  return path.split('/').map(encodeSegment).join('/')
+}
+
+/**
+ * Build the address of a file read through one Session.
+ * @param sessionId - the Session whose Host workspace resolves the path.
+ * @param path - absolute or workspace-relative path; backslashes are normalized
+ *   to `/`, and leading `./` prefixes are dropped.
+ */
+function sessionFileAddress(sessionId: string, path: string): string {
+  const normalized = path.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '')
+  return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(normalized)}`
+}
+
+/**
+ * The address for a path as a caller holds it.
+ * @param sessionId - the Session the path is read in.
+ * @param cwd - that Session's workspace root, when known.
+ * @param path - absolute or workspace-relative path, in either separator spelling.
+ */
+export function fileAddressFor(sessionId: string, cwd: string | undefined, path: string): string {
+  const normalized = path.replace(/\\/g, '/')
+  if (!isAbsoluteWorkspacePath(normalized)) return sessionFileAddress(sessionId, normalized)
+  const root = cwd === undefined ? '' : cwd.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (root !== '' && normalized === root) return sessionFileAddress(sessionId, '')
+  if (root !== '' && normalized.startsWith(`${root}/`)) {
+    return sessionFileAddress(sessionId, normalized.slice(root.length + 1))
+  }
+  return sessionFileAddress(sessionId, normalized)
+}
+
+/**
+ * Build a sidebar file opener for one session, or `undefined` when the
+ * environment cannot open previews (no `sidebarRight` service, no session).
+ * The cwd is re-read per call inside the opener, so a workspace switch between
+ * renders is picked up on the next click.
+ *
+ * @param ctx - the client root context.
+ * @param sessionId - the session whose workspace resolves paths.
+ * @returns an opener that routes a produced path to the Sidebar preview.
+ */
+export function sidebarFileOpener(
+  ctx: Context | undefined,
+  sessionId: string | undefined,
+): ((path: string) => void) | undefined {
+  if (ctx === undefined || sessionId === undefined) return undefined
+  const bar = ctx.get('sidebarRight') as SidebarRightLike | undefined
+  if (bar === undefined || typeof bar.openResource !== 'function') return undefined
+
+  return (path: string) => {
+    const sessions = ctx.get('sessions') as SessionsListLike | undefined
+    const cwd = sessions?.list?.getSnapshot?.().byId?.[sessionId]?.cwd
+    bar.openResource(fileAddressFor(sessionId, cwd, path))
+  }
+}

package/src/client/index.tsx

@@ -0,0 +1,144 @@
+/**
+ * Browser half: the task board tab, plus the shadow that hides the official
+ * composer-band todo panel.
+ *
+ * Registration order matters and is deliberate:
+ *
+ * 1. **Dictionaries first.** Every later registration can render translated
+ *    copy, and a dictionary that lands after the first paint would show raw
+ *    keys for a frame.
+ * 2. **Soft-dependency check.** `inject` already waits for `betterSidebar`, so
+ *    the guard only fires in a composition that relaxes the inject list. It is
+ *    kept because it is what stops the plugin from hiding the official panel
+ *    when it has no board to replace it with.
+ * 3. **Shadow the official dock.** Deliberately BEFORE the tab registration:
+ *    the panel is the only other carrier of the list, so the replacement has to
+ *    exist in the same activation.
+ * 4. **Register the tab.**
+ *
+ * Every registration rides `ctx.effect(fn, label)` so its disposer is revoked on
+ * fiber teardown (HMR / disable), which is also what makes the shadow
+ * reversible: unload the plugin and the official dock renders again.
+ *
+ * Contract notes for the two surfaces touched here:
+ * - better-sidebar tabs are hosted by DSH's native right Sidebar, so the tab
+ *   body receives `TabComponentProps` (`ctx` + `scope` + `visible`) and NOT the
+ *   framework's session-scoped slot props.
+ * - `conversation.input.dock` is the DSH slot the official todo panel occupies;
+ *   see `brief/dock-shadow.tsx` for why a lower priority wins the cell.
+ */
+import { createElement } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import type { BetterSidebarService, TabComponentProps } from 'dsh-better-sidebar/client/service'
+import { SummaryTab } from './SummaryTab'
+import { BriefIcon } from './BriefIcon'
+import { NS, dictionaries } from './locales'
+import { readTodos, unfinishedCount } from './brief/board'
+import { registerTodoDockShadow } from './brief/dock-shadow'
+import { TODOS_KEY } from './brief/use-todos'
+import { projectionSnapshot } from './use-projection'
+
+/**
+ * Tab type id. Package-prefixed so it cannot collide with a built-in type.
+ * Unchanged since the 0.1.0 board tab: the summary tab REPLACES the board tab
+ * in place, so an opened or pinned tab survives the upgrade.
+ */
+export const TAB_ID = 'dsh-brief-sidebar:board'
+
+/**
+ * Position in the host's new-tab guide.
+ *
+ * Built-ins on this host generation sit at editor 10 / git 20 / subagent 30 /
+ * sidechat 35 / terminal 40 / browser 50. 15 places a per-session task board
+ * right after the editor, which is where a reader looks for session state.
+ */
+export const TAB_ORDER = 15
+
+/** Services required before `apply` runs. */
+export const inject = ['betterSidebar', 'locale', 'slots']
+
+/**
+ * Structural view of the DSH locale service — only the two members this plugin
+ * calls. Declared locally on purpose: importing the real type would pull the
+ * whole client type graph into a browser-only plugin for two signatures.
+ */
+interface LocaleLike {
+  register(ns: string, dicts: Record<string, Record<string, string>>): () => void
+  bind(ns: string): (key: string) => string
+}
+
+/**
+ * An effect body must return a disposer (cordis rejects `undefined` with a
+ * `TypeError`), so a path that could not register anything returns this no-op
+ * instead of nothing.
+ */
+const NOOP = (): void => {}
+
+/**
+ * Browser-face apply.
+ *
+ * @param ctx - the client root context.
+ */
+export function apply(ctx: Context): void {
+  // 1. Plugin-owned dictionaries, in one registration.
+  const locale: LocaleLike | undefined = ctx.get('locale')
+  if (locale !== undefined) {
+    ctx.effect(() => locale.register(NS, dictionaries), 'dsh-brief-sidebar: dictionaries')
+  }
+
+  /**
+   * Translate one of our keys. `bind` returns a cached function that reads the
+   * ACTIVE locale at call time, so a language switch needs no re-apply; an
+   * unknown namespace or key falls back to the key itself rather than throwing
+   * inside a render.
+   */
+  const t = (key: string): string => {
+    if (locale === undefined) return key
+    try {
+      return locale.bind(NS)(key) || key
+    } catch {
+      return key
+    }
+  }
+
+  // 2. Soft dependency: without better-sidebar there is no place to show the
+  //    list, so the plugin stays inert and the official panel keeps rendering.
+  const bar: BetterSidebarService | undefined = ctx.get('betterSidebar')
+  if (bar === undefined) return
+
+  // 3. Hide the official composer-band panel (reversible on unload).
+  ctx.effect(() => registerTodoDockShadow(ctx) ?? NOOP, 'dsh-brief-sidebar: dock shadow')
+
+  // 4. The board.
+  ctx.effect(
+    () =>
+      bar.registerTab({
+        id: TAB_ID,
+        title: () => t('tab.title'),
+        description: () => t('tab.desc'),
+        icon: (size: number) => BriefIcon(size),
+        order: TAB_ORDER,
+        // Shorthand for `dedupeKey: () => id`: reopening focuses the existing tab.
+        single: true,
+        /**
+         * Unfinished count on the tab strip. Called on every tab-bar render, so
+         * it reads one snapshot and allocates no subscription; a completed list
+         * shows no badge at all.
+         */
+        badge: (badgeCtx, badgeScope) => {
+          const todos = readTodos(projectionSnapshot(badgeCtx, badgeScope.sessionId, TODOS_KEY))
+          if (todos === undefined) return null
+          const pending = unfinishedCount(todos)
+          return pending > 0 ? pending : null
+        },
+        component: (props: TabComponentProps) =>
+          createElement(SummaryTab, {
+            t,
+            ctx: props.ctx,
+            scope: props.scope,
+            visible: props.visible,
+          }),
+      }),
+    'dsh-brief-sidebar: tab',
+  )
+}

package/src/client/locales.ts

@@ -0,0 +1,78 @@
+/**
+ * Plugin-owned i18n dictionaries.
+ *
+ * Consumer plugins must NOT reach into better-sidebar's internal `t()` or its
+ * `betterSidebar` dictionary namespace, so this plugin registers its own
+ * namespace through the DSH `locale` service. `dsh-brief-sidebar` is outside the
+ * `LocaleNamespaceMap` merge table, which is exactly what the untyped
+ * `register(ns, dicts)` overload is for — but the dictionaries themselves stay
+ * strictly paired: `zh` is the key-set source of truth and `en` is typed as
+ * `Record<keyof typeof zh, string>`, so a missing or extra English key is a
+ * COMPILE error rather than a runtime fallback to the raw key.
+ *
+ * Every key referenced anywhere in `src/**` must exist in both dictionaries;
+ * `tests/purity.spec.ts` asserts that, so a typo in a `t('…')` call cannot
+ * ship as an untranslated literal.
+ */
+
+/** The namespace owned by this plugin (own vocabulary, own lifecycle). */
+export const NS = 'dsh-brief-sidebar'
+
+/** Simplified Chinese dictionary — the key-set source of truth. */
+export const zh = {
+  'tab.title': '概要',
+  'tab.desc': '当前会话的任务、产物与规划文件（只读）',
+  'section.progress': '进展',
+  'section.deliverables': '产物',
+  'board.empty': '当前没有任务',
+  'board.emptyHint': '模型调用 todo_write 之后，任务会出现在这里。',
+  'board.unavailable': '任务暂不可用',
+  'board.unavailableHint': '这个会话还没有收到 todo 数据；宿主推来第一帧后会自动显示。',
+  'status.pending': '待处理',
+  'status.inProgress': '进行中',
+  'status.completed': '已完成',
+  'deliverables.empty': '本回合暂无改动文件',
+  'deliverables.emptyHint': '会话里成功写入或修改文件后，它们会实时出现在这里。',
+  'deliverables.sessionTotal': '本会话共 {count} 个文件',
+  'deliverable.codeplanTag': '规划',
+}
+
+/** The key union: what a `t('…')` call may name inside this namespace. */
+export type BriefKey = keyof typeof zh
+
+/** English dictionary, checked complete against the zh key set. */
+export const en: Record<BriefKey, string> = {
+  'tab.title': 'Summary',
+  'tab.desc': 'Tasks, produced files and plan artifacts of this session (read-only)',
+  'section.progress': 'Progress',
+  'section.deliverables': 'Produced files',
+  'board.empty': 'No tasks yet',
+  'board.emptyHint': 'Tasks show up here once the model calls todo_write.',
+  'board.unavailable': 'Tasks unavailable',
+  'board.unavailableHint':
+    'This session has not received any todo data yet; the board fills in on the first frame.',
+  'status.pending': 'Pending',
+  'status.inProgress': 'In progress',
+  'status.completed': 'Done',
+  'deliverables.empty': 'No files changed in this turn',
+  'deliverables.emptyHint': 'Files written or edited successfully in the session appear here live.',
+  'deliverables.sessionTotal': '{count} files in this session',
+  'deliverable.codeplanTag': 'Plan',
+}
+
+/**
+ * Both locales in the shape the locale service consumes. Registered in ONE
+ * call: the registry rejects a duplicate `(namespace, locale)` pair and the
+ * per-locale form would leave a half-registered namespace if the second call
+ * threw.
+ */
+export const dictionaries: Record<string, Record<string, string>> = { zh, en }
+
+/**
+ * Expand the one `{count}` placeholder the deliverables totals line uses. The
+ * locale binder is a plain key → string lookup (no interpolation machinery),
+ * mirroring how `progressLine` composes its summary from parts.
+ */
+export function expandCount(template: string, count: number): string {
+  return template.replace('{count}', String(count))
+}

package/src/client/summary/DeliverablesSection.tsx

@@ -0,0 +1,192 @@
+/**
+ * The deliverables section: the `dshSummaryDeliverables` projection drawn as
+ * one part of the summary tab.
+ *
+ * Unlike the progress section this is an OPTIONAL capability: where the host
+ * half never registered the unit (older composition, key absent), the section
+ * hides entirely — absence is not an error state here, and the official
+ * "本次产出" row in the conversation flow still covers the turn-end view.
+ * When the projection is live, the latest turn's produced paths update
+ * mid-turn: every successful mutation result publishes a frame, so the reader
+ * sees files appear while the turn is still running, which is exactly the gap
+ * the official turn-tail row has.
+ *
+ * Codeplan artifacts (paths under `.agents/plans/<任务名>/`) are ordinary
+ * produced entries — they are marked with a pill, not split into a separate
+ * section.
+ *
+ * Colours come from `--dsw-alias-*` tokens only (skin contract).
+ */
+import { createElement } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import { DELIVERABLES_KEY } from '../../projection/keys'
+import { useProjectionValue } from '../use-projection'
+import { sidebarFileOpener } from '../file-open'
+import { basename, readDeliverables, splitCodeplanPath } from './deliverables'
+import { expandCount } from '../locales'
+
+export interface DeliverablesSectionProps {
+  /** The DSH locale lookup, passed down from `apply`. */
+  t: (key: string) => string
+  /** The client root context (the tab body's only way to reach services). */
+  ctx?: Context
+  /** The session this tab is scoped to. */
+  scope?: { readonly sessionId?: string }
+}
+
+const SECTION_STYLE: CSSProperties = {
+  flexShrink: 0,
+  borderBottom: '1px solid var(--dsw-alias-border-secondary)',
+}
+
+const HEADER_STYLE: CSSProperties = {
+  padding: '10px 12px 0',
+  color: 'var(--dsw-alias-label-secondary)',
+  fontSize: 12,
+  fontWeight: 600,
+}
+
+const LIST_STYLE: CSSProperties = {
+  listStyle: 'none',
+  margin: 0,
+  padding: '6px 0',
+  display: 'flex',
+  flexDirection: 'column',
+}
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 8,
+  padding: '6px 12px',
+}
+
+const TOTAL_STYLE: CSSProperties = {
+  padding: '6px 12px 10px',
+  color: 'var(--dsw-alias-label-tertiary)',
+  fontSize: 12,
+}
+
+const PATH_STYLE: CSSProperties = {
+  minWidth: 0,
+  overflowWrap: 'anywhere',
+  color: 'var(--dsw-alias-label-secondary)',
+}
+
+/** Row-as-button reset: the row itself is the click target, content unchanged. */
+const BUTTON_STYLE: CSSProperties = {
+  ...PATH_STYLE,
+  background: 'none',
+  border: 'none',
+  font: 'inherit',
+  fontSize: 'inherit',
+  color: 'var(--dsw-alias-label-secondary)',
+  padding: 0,
+  textAlign: 'left',
+  cursor: 'pointer',
+}
+
+/** The codeplan pill: same form as the status pills, tertiary emphasis. */
+const TAG_STYLE: CSSProperties = {
+  flexShrink: 0,
+  color: 'var(--dsw-alias-label-tertiary)',
+  border: '1px solid var(--dsw-alias-label-tertiary)',
+  borderRadius: 999,
+  padding: '0 6px',
+  fontSize: 11,
+  lineHeight: '16px',
+  whiteSpace: 'nowrap',
+}
+
+/**
+ * One produced-file row. When the sidebar opener is available the row is a
+ * button that routes the path to the Sidebar preview (the same channel the
+ * conversation's produced-file chips use); otherwise it degrades to a plain
+ * span. A codeplan artifact carries the pill either way.
+ */
+function PathRow(props: {
+  path: string
+  t: (key: string) => string
+  open?: (path: string) => void
+}): ReactNode {
+  const { path, t, open } = props
+  const plan = splitCodeplanPath(path)
+  const title = plan === null ? path : `${t('deliverable.codeplanTag')}: ${plan.task} · ${path}`
+  const label = basename(path)
+  const content = plan === null ? null : createElement('span', { style: TAG_STYLE }, t('deliverable.codeplanTag'))
+  if (open === undefined) {
+    return createElement(
+      'li',
+      { style: ROW_STYLE },
+      content,
+      createElement('span', { style: PATH_STYLE, title }, label),
+    )
+  }
+  return createElement(
+    'li',
+    { style: ROW_STYLE },
+    content,
+    createElement('button', { style: BUTTON_STYLE, title, onClick: () => { open(path) } }, label),
+  )
+}
+
+/**
+ * The deliverables section. The subscription is unconditional (a plain
+ * listener, not IO).
+ * @param props - translation, client context, session scope.
+ */
+export function DeliverablesSection(props: DeliverablesSectionProps): ReactNode {
+  const { t, ctx, scope } = props
+
+  const view = readDeliverables(useProjectionValue(ctx, scope?.sessionId, DELIVERABLES_KEY))
+
+  // Capability absent — the optional unit never registered. Hide, don't nag.
+  if (view === undefined) return null
+
+  // Optional click-to-preview: rows degrade to plain text where the sidebar
+  // service is absent (the opener resolves the session cwd per click).
+  const open = sidebarFileOpener(ctx, scope?.sessionId)
+
+  const latestPaths = view.latest?.paths ?? []
+
+  if (latestPaths.length === 0 && view.sessionTotal === 0) {
+    return createElement(
+      'div',
+      { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'deliverables-section' },
+      createElement('div', { style: HEADER_STYLE }, t('section.deliverables')),
+      createElement(
+        'div',
+        {
+          style: {
+            margin: '0 auto',
+            padding: 24,
+            maxWidth: 460,
+            textAlign: 'center',
+            color: 'var(--dsw-alias-label-tertiary)',
+            lineHeight: 1.7,
+            fontSize: 12,
+          },
+        },
+        createElement('div', { style: { marginBottom: 6, color: 'var(--dsw-alias-label-secondary)' } }, t('deliverables.empty')),
+        createElement('div', null, t('deliverables.emptyHint')),
+      ),
+    )
+  }
+
+  return createElement(
+    'div',
+    { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'deliverables-section' },
+    createElement('div', { style: HEADER_STYLE }, t('section.deliverables')),
+    createElement(
+      'ul',
+      { style: LIST_STYLE },
+      latestPaths.map(path => createElement(PathRow, { key: path, path, t, open })),
+    ),
+    createElement(
+      'div',
+      { style: TOTAL_STYLE },
+      expandCount(t('deliverables.sessionTotal'), view.sessionTotal),
+    ),
+  )
+}

package/src/client/summary/deliverables.ts

@@ -0,0 +1,93 @@
+/**
+ * The `dshSummaryDeliverables` projection — reading and classifying it.
+ *
+ * The Host computes this projection (this plugin's own node half registers the
+ * unit) and pushes finished whole values; the client never folds it. This
+ * module is the read side of that contract and is deliberately PURE — no
+ * React, no context, no IO — so the narrowing and the codeplan classification
+ * can be tested directly.
+ */
+import type { DeliverablesView } from '../../projection/keys'
+
+/**
+ * Narrow a raw projection value into a deliverables view.
+ *
+ * Two outcomes are kept apart on purpose, mirroring the store's contract:
+ * - `undefined` — the capability is ABSENT (the host half never registered —
+ *   e.g. an older composition — or no frame carried the key yet);
+ * - a view — the projection is live. A view with `latest: null` and
+ *   `sessionTotal: 0` IS the empty state; the fold starts publishing as soon
+ *   as the unit registers, so "present but empty" is a real value here, not a
+ *   sentinel.
+ *
+ * @param value - the raw `unknown` snapshot of the deliverables face.
+ * @returns the validated view, or `undefined` when the capability is absent.
+ */
+export function readDeliverables(value: unknown): DeliverablesView | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const raw = value as { latest?: unknown; sessionPaths?: unknown; sessionTotal?: unknown }
+  if (raw.latest === undefined || raw.sessionPaths === undefined || raw.sessionTotal === undefined) {
+    return undefined
+  }
+  if (!isBucket(raw.latest) || !Array.isArray(raw.sessionPaths) || typeof raw.sessionTotal !== 'number') {
+    return undefined
+  }
+  const paths = raw.sessionPaths.filter((path): path is string => typeof path === 'string')
+  return {
+    latest: raw.latest === null ? null : { turn: raw.latest.turn, paths: raw.latest.paths },
+    sessionPaths: paths,
+    sessionTotal: raw.sessionTotal,
+  }
+}
+
+/** Whether a value is a well-formed latest-turn bucket (or explicitly null). */
+function isBucket(value: unknown): value is { turn: number; paths: readonly string[] } | null {
+  if (value === null) return true
+  if (typeof value !== 'object') return false
+  const bucket = value as { turn?: unknown; paths?: unknown }
+  return typeof bucket.turn === 'number' && Array.isArray(bucket.paths)
+}
+
+/**
+ * The path prefix that identifies a codeplan artifact. The codeplan skill
+ * writes its four fixed artifacts under `$workspace\.agents\plans\<任务名>\`;
+ * produced paths may spell the separators either way.
+ */
+const CODEPLAN_SEGMENT = '.agents/plans/'
+
+/**
+ * Normalize path separators so one spelling of the codeplan prefix matches.
+ * Only classification uses this; the displayed path keeps the tool's exact
+ * spelling.
+ */
+function normalized(path: string): string {
+  return path.replaceAll('\\', '/')
+}
+
+/** Whether a produced path is a codeplan artifact. */
+export function isCodeplanPath(path: string): boolean {
+  return normalized(path).includes(CODEPLAN_SEGMENT)
+}
+
+/**
+ * Split a codeplan path into its task name and file name.
+ *
+ * @param path - a produced path; need not actually be a codeplan artifact.
+ * @returns task and file names, or `null` when the path is not under the
+ *   codeplan plans directory (or names no file beneath the task folder).
+ */
+export function splitCodeplanPath(path: string): { task: string; file: string } | null {
+  const marker = normalized(path).indexOf(CODEPLAN_SEGMENT)
+  if (marker < 0) return null
+  const rest = normalized(path).slice(marker + CODEPLAN_SEGMENT.length)
+  const slash = rest.indexOf('/')
+  if (slash <= 0 || slash === rest.length - 1) return null
+  return { task: rest.slice(0, slash), file: rest.slice(slash + 1) }
+}
+
+/** The final path segment, under either separator. */
+export function basename(path: string): string {
+  const normalizedPath = normalized(path)
+  const slash = normalizedPath.lastIndexOf('/')
+  return slash < 0 ? normalizedPath : normalizedPath.slice(slash + 1)
+}