create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/usage-ledger/dsh-parse.js

@@ -0,0 +1,152 @@
+'use strict';
+
+// DeepSeek Harness (`dsh`) usage-row parser for the usage ledger (design
+// docs/deepseek-harness-acp-agent-2026-10-28.html §5 D-19 and §9b L-3..L-8).
+//
+// The ONE source of dsh spend is the model proxy's per-request file,
+// `<dataDir>/dsh-usage/<ctmSessionId>.jsonl` (written by lib/acp/dsh-usage-log.js; that contract is
+// FROZEN -- this parser reads it, it never redefines it). One JSON object per line:
+//
+//   {"ts":"<ISO-8601 UTC>","requestId":"<id>","model":"<wire model id>","input_tokens":N,
+//    "output_tokens":N,"cache_read_input_tokens":N,"cache_creation_input_tokens":N}
+//
+// A line that is not JSON, or is JSON that is not an object, carries no call: the reader counts it
+// (usage_files.skipped_lines) and keeps going. Nothing a malformed line says is ever guessed at.
+//
+// Pure by construction: it takes an already-parsed JSON object per line and returns facts. No fs, no
+// DB, no try/catch (the caller owns the read loop and the JSON.parse), exactly like codex-parse.js.
+//
+// Unlike a Claude/Codex transcript this file is APPEND-ONLY and holds nothing but calls, so there is
+// no turn, prompt, spawn, delegation or agent fact to derive from it:
+//   * `prompt_id` is NULL. The file states spend, not conversation; inventing a prompt identity from
+//     a request id would claim an attribution the source cannot support.
+//   * `agent_id` is '' -- the ledger's convention for the SESSION's main agent (the same spelling
+//     claude-parse.js uses for a root transcript). dsh has no sub-agents of its own.
+//
+// Identity: `requestId` IS the call's identity (the contract says so), so the call key is
+// `dsh:<requestId>` and the same id written twice is ONE call. The id is also stored beside the key
+// as `request_id`, the evidence column every provider's call row carries.
+
+// The directory whose `*.jsonl` files are dsh usage rows (ingest.js decides the provider by it).
+const DSH_USAGE_DIR_NAME = 'dsh-usage';
+const DSH_CALL_KEY_PREFIX = 'dsh:';
+
+/**
+ * The CTM session id a dsh usage file belongs to: its own file name without the extension (the
+ * frozen contract of lib/acp/dsh-usage-log.js -- the name IS the id, never a directory lookup).
+ *
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+function dshFileSessionId(filePath) {
+  const clean = String(filePath || '').replace(/\\/g, '/');
+  const base = clean.slice(clean.lastIndexOf('/') + 1);
+  const match = /^(.+)\.jsonl$/.exec(base);
+  return match ? match[1] : null;
+}
+
+// Non-negative integer token count. A missing, malformed or negative value is 0 -- the columns are
+// NOT NULL integers where 0 already means "the provider reported nothing", never a separate state.
+function count(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return Math.round(n);
+}
+
+// The call's identity. An absent or non-string `requestId` names no call the proxy could have
+// written twice under one id, so the LINE OFFSET stands in: it is stable for a given append-only
+// file, so a re-read of the same bytes keys identically instead of minting a second call.
+function callKeyFor(requestId, lineOffset) {
+  const id = typeof requestId === 'string' ? requestId : (typeof requestId === 'number' && Number.isFinite(requestId) ? String(requestId) : '');
+  return id === '' ? `${DSH_CALL_KEY_PREFIX}line:${lineOffset}` : `${DSH_CALL_KEY_PREFIX}${id}`;
+}
+
+// The call-row shape the store accepts, field for field the shape codex-parse.js hands it.
+//   * `input` is the UNCACHED input: the Anthropic Messages API (what dsh speaks) reports
+//     `input_tokens` WITHOUT the cache read/creation halves, so nothing is subtracted here (Codex's
+//     OpenAI-shaped totals, which DO include the cached prefix, are the case that subtracts).
+//   * `cache_write_1h` is 0: the contract carries one cache-creation count, and the 5-minute bucket
+//     is the only one that backs it.
+function callRowFromRow(record, { callKey, requestId, sessionId, lineOffset }) {
+  return {
+    call_key: callKey,
+    provider: 'dsh',
+    session_id: sessionId,
+    // '' is the session's MAIN agent (the ledger convention, see claude-parse.js).
+    agent_id: '',
+    // No prompt attribution is derivable from a usage row alone (see the header).
+    prompt_id: null,
+    ts: Date.parse(record.ts) || 0,
+    model: typeof record.model === 'string' && record.model !== '' ? record.model : null,
+    input: count(record.input_tokens),
+    output: count(record.output_tokens),
+    cache_read: count(record.cache_read_input_tokens),
+    cache_write_5m: count(record.cache_creation_input_tokens),
+    cache_write_1h: 0,
+    reasoning: 0,
+    // A dsh row IS the final reading of its own request: the proxy writes it once, when the request
+    // completed, so the counts are never a lower bound on a response still being streamed.
+    output_final: 1,
+    basis: 'record',
+    request_id: requestId,
+    line_offset: lineOffset,
+  };
+}
+
+/**
+ * @param {{sessionId?: string|null, state?: object|null}} [options]
+ *   `sessionId` is the CTM session id every call of this file belongs to (its file name).
+ *   `state` is the checkpoint's parse state. This parser derives nothing across lines, so the state
+ *   is carried only to keep the checkpoint shape identical to the other parsers'.
+ */
+function createDshFileParser({ sessionId = null, state = null } = {}) {
+  const persisted = state && typeof state === 'object' ? state : {};
+  let calls = [];
+  // The ids this pass has already emitted: a repeated requestId is ONE call, not two rows the store
+  // would then have to collapse. Cleared per drain (the batch is the dedup window); a duplicate that
+  // straddles a slice boundary still collapses in the store, whose call_key is the durable identity.
+  let seen = new Set();
+
+  function line(record, lineOffset) {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return;
+    const offset = Number(lineOffset) || 0;
+    const callKey = callKeyFor(record.requestId, offset);
+    if (seen.has(callKey)) return;
+    seen.add(callKey);
+    calls.push(callRowFromRow(record, {
+      callKey,
+      requestId: typeof record.requestId === 'string' ? record.requestId : (typeof record.requestId === 'number' && Number.isFinite(record.requestId) ? String(record.requestId) : null),
+      sessionId,
+      lineOffset: offset,
+    }));
+  }
+
+  function drain() {
+    const out = {
+      calls,
+      // dsh states spend only: no prompt, spawn, alias, delegation, attempt or agent fact exists in
+      // this source, and an empty array is the honest answer for each (never a fabricated one).
+      prompts: [],
+      aliases: [],
+      spawns: [],
+      delegations: [],
+      attempts: [],
+      agents: [],
+      reported: null,
+      state: persisted,
+    };
+    calls = [];
+    seen = new Set();
+    return out;
+  }
+
+  return { line, drain };
+}
+
+module.exports = {
+  createDshFileParser,
+  dshFileSessionId,
+  callKeyFor,
+  DSH_USAGE_DIR_NAME,
+  DSH_CALL_KEY_PREFIX,
+};

package/template/coding-task-manager/lib/usage-ledger/dsh-read.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// The read model's dsh rules (design docs/deepseek-harness-acp-agent-2026-10-28.html §5 D-19, §9b L-8).
+// Path arithmetic only: this module opens no file, so lib/usage-ledger/read.js can load it in the read pool.
+//
+// dsh is the ONE provider whose ledger rows are not keyed by an `agent_sessions.agent_session_id`: the
+// model proxy names a session's usage file `<dataDir>/dsh-usage/<ctmSessionId>.jsonl`
+// (lib/acp/dsh-usage-log.js), so the ledger's `session_id` IS the CTM session id.
+//
+// The usage file is NOT the session's `agent_sessions.jsonl_path`. That column names the CTM-owned
+// TRANSCRIPT (`<dataDir>/dsh-transcripts/<acpSessionId>.jsonl`, design D-8), which carries no token usage
+// AND whose `{type:'user'}` rows the Claude parser would admit as PROMPTS if it were ever handed to the
+// writer as a source. The usage file lives in the sibling directory, named by the CTM session id; it is
+// derived from the transcript path so the SCOPE and the CATALOG cannot disagree about where a session's
+// dsh rows are. tests-integration/usage-ledger-dsh.test.js proves this path equals the ingested one
+// (`coverage.complete` is true only then).
+
+const path = require('node:path');
+const { DSH_USAGE_DIR_NAME } = require('./dsh-parse');
+
+const DSH_TRANSCRIPT_DIR_NAME = 'dsh-transcripts';
+
+/**
+ * The usage file the ledger stores a dsh session's rows under, or null when the transcript path does not
+ * name a `<dataDir>/dsh-transcripts/<acp>.jsonl` file.
+ *
+ * @param {string|null|undefined} transcriptPath `agent_sessions.jsonl_path` of a dsh row
+ * @param {string|null|undefined} ctmSessionId the CTM session id the usage file is named after
+ * @returns {string|null}
+ */
+function dshUsageSourcePath(transcriptPath, ctmSessionId) {
+  const id = String(ctmSessionId == null ? '' : ctmSessionId);
+  const file = String(transcriptPath == null ? '' : transcriptPath);
+  if (!id || !file) return null;
+  const transcriptDir = path.dirname(file);
+  if (path.basename(transcriptDir) !== DSH_TRANSCRIPT_DIR_NAME) return null;
+  const dataDir = path.dirname(transcriptDir);
+  if (!dataDir || dataDir === '.' || dataDir === path.sep) return null;
+  return path.join(dataDir, DSH_USAGE_DIR_NAME, `${id}.jsonl`);
+}
+
+/**
+ * A scope entry for a dsh `agent_sessions` row: re-keyed to the CTM session it belongs to, its source the
+ * usage file. The core db's size/mtime describe the TRANSCRIPT, so they are reported unknown rather than
+ * compared against a different file (which would call every dsh session stale). A session the proxy never
+ * wrote a file for reads as no rows, no error.
+ */
+function dshScopeEntry(row, role, ctmId) {
+  const sessionId = row.ctm_session_id == null || row.ctm_session_id === '' ? String(ctmId) : String(row.ctm_session_id);
+  return {
+    session_id: sessionId,
+    provider: 'dsh',
+    ctm_session_id: sessionId,
+    role,
+    source_path: dshUsageSourcePath(row.jsonl_path, sessionId),
+    expected_size: null,
+    expected_modified_at: null,
+    expected_compact_bak_size: null,
+  };
+}
+
+/**
+ * A source-catalog entry for a dsh row, or null when its usage file cannot be named (an empty path is not
+ * ingestable). `session_id` stays the row's `agent_session_id` -- the catalog page's cursor key.
+ */
+function dshCatalogSource(row) {
+  const ctmSessionId = row.ctm_session_id == null ? '' : String(row.ctm_session_id);
+  const sourcePath = dshUsageSourcePath(row.path, ctmSessionId);
+  if (!sourcePath) return null;
+  return { provider: 'dsh', session_id: row.session_id == null ? '' : String(row.session_id), path: sourcePath, size: null, modified_at: null };
+}
+
+module.exports = { DSH_TRANSCRIPT_DIR_NAME, dshUsageSourcePath, dshScopeEntry, dshCatalogSource };

package/template/coding-task-manager/lib/usage-ledger/ingest.js

@@ -26,6 +26,7 @@ const {
   CLAUDE_MARKERS,
 } = require('./claude-parse');
 const { createCodexFileParser, CODEX_MARKERS } = require('./codex-parse');
+const { createDshFileParser, dshFileSessionId, DSH_USAGE_DIR_NAME } = require('./dsh-parse');
 
 // Bump when a parser's READING of a record changes: a checkpoint stamped with another
 // version is discarded and the file is re-read from 0 (D-3). Upserts are idempotent,
@@ -49,7 +50,11 @@ const { createCodexFileParser, CODEX_MARKERS } = require('./codex-parse');
 // promptId of the prompt it continues no longer relabels that row's kind, and a `delegate` result
 // with no `generation` key resolves to generation 1 instead of dropping its edge. Both are
 // corrections to facts already stored, so the re-read this version forces is what repairs them.
-const PARSER_VERSION = 7;
+// v8 (deepseek-harness-acp-agent WP-9, design D-19): the dsh provider exists. Its source --
+// `<dataDir>/dsh-usage/<ctmSessionId>.jsonl` -- is a NEW file this reading discovers, so nothing
+// already stored changes shape; the bump is what makes every stored dsh file (should one ever be
+// written before the provider was known) get read through the parser below.
+const PARSER_VERSION = 8;
 // The head fingerprint is the first min(size, 4096) bytes (D-3).
 const HEAD_BYTES = 4096;
 const DEFAULT_SLICE_BYTES = 8 * 1024 * 1024;
@@ -66,16 +71,22 @@ function sha256Hex(buf) {
 }
 
 /**
- * Which provider owns `sourcePath`: 'codex' for a rollout file, 'claude' for a
- * Claude Code transcript, null for anything else.
+ * Which provider owns `sourcePath`: 'codex' for a rollout file, 'dsh' for a DeepSeek Harness usage
+ * file (`<dataDir>/dsh-usage/<ctmSessionId>.jsonl`), 'claude' for a Claude Code transcript, null for
+ * anything else.
+ *
+ * The dsh test is the PARENT DIRECTORY NAME, and it is evaluated BEFORE the Claude identity: a dsh
+ * file is `<session-id>.jsonl`, which `claudeFileIdentity` would otherwise accept as a Claude root
+ * transcript (its rule is any `<name>.jsonl`). Only the directory separates the two providers.
  *
  * @param {string} sourcePath
- * @returns {'claude'|'codex'|null}
+ * @returns {'claude'|'codex'|'dsh'|null}
  */
 function fileProvider(sourcePath) {
   const p = String(sourcePath || '');
   if (!p) return null;
   if (CODEX_ROLLOUT_RE.test(path.basename(p))) return 'codex';
+  if (/\.jsonl$/i.test(path.basename(p)) && path.basename(path.dirname(p)) === DSH_USAGE_DIR_NAME) return 'dsh';
   if (claudeFileIdentity(p)) return 'claude';
   return null;
 }
@@ -154,14 +165,21 @@ function createUsageIngestor({ store, sliceBytes = DEFAULT_SLICE_BYTES, pricer =
     }
 
     const identity = provider === 'claude' ? claudeFileIdentity(sourcePath) : null;
-    const markers = provider === 'claude' ? CLAUDE_MARKERS : CODEX_MARKERS;
+    // A dsh file's session id IS its file name (the frozen contract of lib/acp/dsh-usage-log.js), so
+    // it is known before a single byte is read -- unlike Codex, whose thread ids appear in the file.
+    const dshSessionId = provider === 'dsh' ? dshFileSessionId(sourcePath) : null;
+    // Every dsh line is a call, so there is no marker to prefilter on (null = deliver every complete
+    // line; a line that is not JSON is counted by the read loop, never guessed at).
+    const markers = provider === 'claude' ? CLAUDE_MARKERS : (provider === 'codex' ? CODEX_MARKERS : null);
     const metaAgent = provider === 'claude' && identity.agentId && offset === 0
       ? readMetaAgent(sourcePath, identity)
       : null;
 
     const parser = provider === 'claude'
       ? createClaudeFileParser({ sessionId: identity.sessionId, agentId: identity.agentId, state })
-      : createCodexFileParser({ state, sourcePath });
+      : (provider === 'dsh'
+        ? createDshFileParser({ sessionId: dshSessionId, state })
+        : createCodexFileParser({ state, sourcePath }));
 
     // The file identity of a batch. For Codex the root session id and the thread id only
     // appear once session_meta / token_usage_record has been read, so it is recomputed
@@ -176,6 +194,16 @@ function createUsageIngestor({ store, sliceBytes = DEFAULT_SLICE_BYTES, pricer =
           agent_id: identity.agentId,
         };
       }
+      if (provider === 'dsh') {
+        // A dsh file is ONE session (its name): the id never arrives from a line, so it is the same
+        // on every pass and `agent_id` '' names that session's main agent.
+        return {
+          source_path: sourcePath,
+          provider,
+          session_id: dshSessionId,
+          agent_id: '',
+        };
+      }
       const s = parserState || {};
       return {
         source_path: sourcePath,

package/template/coding-task-manager/lib/usage-ledger/live.js

@@ -29,18 +29,33 @@ const DEFAULT_MAX_BYTES_PER_FILE = 4 * 1024 * 1024;
 const MAX_ERRORS = 20;
 const CODEX_ROLLOUT_RE = /^rollout-.*\.jsonl$/;
 const CLAUDE_AGENT_RE = /^agent-.*\.jsonl$/;
+const DSH_USAGE_FILE_RE = /\.jsonl$/i;
+// Every provider this lane can be handed a root for. A root naming anything else is defaulted to
+// 'claude' (the historical spelling) rather than silently admitted as itself.
+const LIVE_PROVIDERS = new Set(['claude', 'codex', 'dsh']);
 
 // `<...>/<sid>.jsonl` or `<...>/<sid>.jsonl.bak` -> `<...>/<sid>/subagents`.
 function claudeSubagentsDir(rootPath) {
   return path.join(String(rootPath).replace(/\.jsonl(?:\.bak)?$/i, ''), 'subagents');
 }
 
+// The directory a source's SIBLING files live in, and the key that identifies it as a discovery root.
+// Codex and dsh both scan one FLAT directory (Codex `sessions/`, dsh `<dataDir>/dsh-usage/`, whose
+// file names are CTM session ids); Claude's siblings are the `<sid>/subagents` tree beside a root
+// transcript. The key is prefixed per provider so a Codex sessions dir and a dsh dir can never
+// collide.
+function discoveryDirKey(provider, rootPath) {
+  if (provider === 'codex') return `codex:${path.dirname(rootPath)}`;
+  if (provider === 'dsh') return `dsh:${path.dirname(rootPath)}`;
+  return claudeSubagentsDir(rootPath);
+}
+
 // A root list normalized to `{provider, path}` with the provider defaulted. Pure and
 // exported so both the lane and the worker's change detector agree on one shape.
 function normalizeRoots(next) {
   return (Array.isArray(next) ? next : [])
     .filter((root) => root && typeof root.path === 'string' && root.path)
-    .map((root) => ({ provider: root.provider === 'codex' ? 'codex' : 'claude', path: root.path }));
+    .map((root) => ({ provider: LIVE_PROVIDERS.has(root.provider) ? root.provider : 'claude', path: root.path }));
 }
 
 // The identity of a root set: sorted `provider:path`. The worker fires its prompt
@@ -80,11 +95,16 @@ function createLiveLane({
   const priority = new Map();
   function discoveryRoot(source) {
     if (source.provider === 'codex') return null; // inactive Codex sources are supplied by the native catalog
+    // dsh has no catalog of its own: one flat directory holds every session's file, so ANY dsh root
+    // (the source itself, or a file the caller requested) makes the whole directory discoverable.
+    if (source.provider === 'dsh') return { ...source, key: discoveryDirKey('dsh', source.path) };
     const identity = claudeFileIdentity(source.path);
     return identity && !identity.agentId ? { ...source, key: claudeSubagentsDir(source.path) } : null;
   }
   function enqueueDiscovery(source, { active = false, urgent = false } = {}) {
-    const root = source.provider === 'codex' && active ? { ...source, key: `codex:${path.dirname(source.path)}` } : discoveryRoot(source);
+    const root = (source.provider === 'codex' || source.provider === 'dsh') && active
+      ? { ...source, key: discoveryDirKey(source.provider, source.path) }
+      : discoveryRoot(source);
     if (!root) return true;
     const previous = discoveryRoots.get(root.key);
     if (previous) { previous.active ||= active; previous.urgent ||= urgent; return true; }
@@ -97,7 +117,7 @@ function createLiveLane({
     const cap = urgent ? PRIORITY_SOURCE_CAP : SOURCE_QUEUE_CAP;
     const result = (accepted) => ({ accepted, backlog: pending.size + priority.size, priorityBacklog: priority.size, catalogBacklog: pending.size, discoveryBacklog: discoveryRoots.size });
     if (!Array.isArray(sources) || sources.length > SOURCE_BATCH_CAP) return result(false);
-    if (sources.some((source) => !source || typeof source.path !== 'string' || !path.isAbsolute(source.path) || !['claude', 'codex'].includes(source.provider))) return result(false);
+    if (sources.some((source) => !source || typeof source.path !== 'string' || !path.isAbsolute(source.path) || !LIVE_PROVIDERS.has(source.provider))) return result(false);
     const normalized = normalizeRoots(sources);
     const fresh = normalized.filter((source) => !queue.has(source.path) && (urgent || !priority.has(source.path)));
     if (queue.size + new Set(fresh.map((source) => source.path)).size > cap) return result(false);
@@ -117,7 +137,7 @@ function createLiveLane({
 
   function setRoots(next) {
     roots = normalizeRoots(next);
-    const activeDirs = new Set(roots.map((root) => root.provider === 'codex' ? `codex:${path.dirname(root.path)}` : claudeSubagentsDir(root.path)));
+    const activeDirs = new Set(roots.map((root) => discoveryDirKey(root.provider, root.path)));
     for (const entry of discoveryRoots.values()) entry.active = activeDirs.has(entry.key);
     for (const root of roots) enqueueDiscovery(root, { active: true });
   }
@@ -136,12 +156,19 @@ function createLiveLane({
     }
     {
       yield null; // one root-work unit even when its directories do not exist
-      const dir = root.provider === 'codex' ? path.dirname(root.path) : claudeSubagentsDir(root.path);
+      // Codex and dsh both list ONE flat directory; Claude's siblings live in `<sid>/subagents`.
+      // `recentOnly` keeps the Codex sessions tree bounded to recently touched rollouts -- a dsh
+      // usage directory holds one small file per session, so every file in it is worth a stat.
+      const dir = root.provider === 'codex' || root.provider === 'dsh'
+        ? path.dirname(root.path)
+        : claudeSubagentsDir(root.path);
+      const fileRe = root.provider === 'codex' ? CODEX_ROLLOUT_RE
+        : (root.provider === 'dsh' ? DSH_USAGE_FILE_RE : CLAUDE_AGENT_RE);
       for (const entry of entries(dir)) {
-        yield entry.isFile && (root.provider === 'codex' ? CODEX_ROLLOUT_RE : CLAUDE_AGENT_RE).test(entry.name)
+        yield entry.isFile && fileRe.test(entry.name)
           ? { provider: root.provider, path: path.join(dir, entry.name), recentOnly: root.provider === 'codex' } : null;
       }
-      if (root.provider === 'codex') return;
+      if (root.provider === 'codex' || root.provider === 'dsh') return; // no `workflows/` walk: flat only
       const workflows = path.join(dir, 'workflows');
       for (const workflow of entries(workflows)) {
         yield null;
@@ -273,4 +300,4 @@ function createLiveLane({
   return { setRoots, requestSources, tick, close, currentFiles: () => current };
 }
 
-module.exports = { SOURCE_QUEUE_CAP, SOURCE_BATCH_CAP, PRIORITY_SOURCE_CAP, DISCOVERY_ROOT_CAP, OPEN_DISCOVERY_CAP, KNOWN_SWEEP_LIMIT, BACKGROUND_BYTES, createLiveLane, normalizeRoots, rootsKey, claudeSubagentsDir };
+module.exports = { SOURCE_QUEUE_CAP, SOURCE_BATCH_CAP, PRIORITY_SOURCE_CAP, DISCOVERY_ROOT_CAP, OPEN_DISCOVERY_CAP, KNOWN_SWEEP_LIMIT, BACKGROUND_BYTES, createLiveLane, normalizeRoots, rootsKey, claudeSubagentsDir, discoveryDirKey, LIVE_PROVIDERS };

package/template/coding-task-manager/lib/usage-ledger/read.js

@@ -7,11 +7,13 @@
 // (workers/read-pool-worker.js), the same way store.js is loaded only inside the writer worker.
 //
 // Entry points:
-//   resolveScope(coreDb, ctmSessionId)         -- CTM id -> the PROVIDER session ids whose
+//   resolveScope(coreDb, ctmSessionId)          -- CTM id -> the PROVIDER session ids whose
 //                                                 ledger rows belong to it (the ledger's
 //                                                 session_id is the provider session id: the
-//                                                 Claude root transcript uuid, or the Codex
-//                                                 root thread id), plus the durable
+//                                                 Claude root transcript uuid, the Codex
+//                                                 root thread id, or -- for dsh -- the CTM
+//                                                 session id itself, which is what its usage
+//                                                 file is NAMED), plus the durable
 //                                                 source/mapping coverage of that scope.
 //   sourceHints(scope)                         -- the internal (path-bearing) work hints the
 //                                                 runtime WP feeds to the writer. Never public.
@@ -31,7 +33,9 @@
 //     `agent_session_id` equals it while a `ctm_sessions` row carries that id
 //     (`LEFT JOIN ctm_sessions c ON c.id = a.agent_session_id`) -- role 'self';
 //   * the CTM sessions in `worker_sessions WHERE parent_ctm_session_id = <ctm id>`
-//     recurse the same mapping with role 'delegated' (depth <= 4, cycle-safe).
+//     recurse the same mapping with role 'delegated' (depth <= 4, cycle-safe);
+//   * dsh (WP-9, D-19): the ledger's session_id IS the CTM session id (the usage file is named by it);
+//     lib/usage-ledger/dsh-read.js owns that mapping.
 //
 // D-1 (durable membership): a worker's UI lifecycle never changes what it COST. A hidden,
 // completed or resumed worker keeps every provider root mapping it ever had, so the
@@ -78,12 +82,15 @@ const CALLS_MAX_LIMIT = 500;
 const SOURCE_CATALOG_DEFAULT_LIMIT = 200;
 const SOURCE_CATALOG_MAX_LIMIT = 200;
 
+const { dshScopeEntry, dshCatalogSource } = require('./dsh-read');
+
 // The parser version the live ingest lane stamps (lib/usage-ledger/ingest.js PARSER_VERSION).
 // read.js keeps its own copy so the read model stays loadable without the transcript parsers;
 // a checkpoint stamped with any other version was written by an older READING of the record,
 // so its source is stale until the re-read lands. tests/usage-ledger-read.test.js pins the two
 // constants equal, so a parser bump cannot drift silently out of this comparison.
-const CURRENT_PARSER_VERSION = 7;
+// v8 (deepseek-harness-acp-agent WP-9): the dsh provider's usage files are a new reading.
+const CURRENT_PARSER_VERSION = 8;
 
 // usage_calls columns the public Call carries -- everything except source_file_id and
 // line_offset (file-storage detail, not part of the read model).
@@ -392,7 +399,7 @@ function resolveScope(coreDb, ctmSessionId) {
            COALESCE(${owner}${hasCtmSessions ? ', c.id' : ''}) AS ctm_session_id${sourceSelect}${tokenSelect}
       FROM agent_sessions a
       ${join}
-     WHERE lower(COALESCE(a.provider, '')) IN ('claude', 'codex')`;
+     WHERE lower(COALESCE(a.provider, '')) IN ('claude', 'codex', 'dsh')`;
 
   // One probe row past the cap: the walk stops at exactly MAX_PROVIDER_SESSIONS and says so.
   const providersFor = coreDb.prepare(`${rootSelect}
@@ -429,7 +436,7 @@ function resolveScope(coreDb, ctmSessionId) {
                        ORDER BY ctm_session_id LIMIT @limit`)
     : null;
 
-  const entryFor = (row, role, ctmId) => ({
+  const entryFor = (row, role, ctmId) => (row.provider === 'dsh' ? dshScopeEntry(row, role, ctmId) : {
     session_id: String(row.session_id),
     provider: row.provider,
     ctm_session_id: row.ctm_session_id == null ? ctmId : row.ctm_session_id,
@@ -520,7 +527,8 @@ function resolveScope(coreDb, ctmSessionId) {
   }
 
   for (const row of providerSessions) {
-    if (!hasPathColumn) {
+    // A dsh source path is derived (lib/usage-ledger/dsh-read.js), never read from a path column.
+    if (!hasPathColumn && row.provider !== 'dsh') {
       missingMappings.push({
         ctm_session_id: row.ctm_session_id,
         role: row.role,
@@ -633,11 +641,13 @@ function sourceHints(scope) {
 }
 
 /**
- * One keyset page of every supported (Claude/Codex) source the core db knows about, ordered by
+ * One keyset page of every supported (Claude/Codex/dsh) source the core db knows about, ordered by
  * agent_session_id (design D-2). Discovery is INDEPENDENT of terminal state: hidden workers and
  * native subagents are sources like any other. No prompt text, no transcript bytes -- metadata
  * only. `next` is the agent_session_id to resume AFTER, or null at the end of the catalog.
  *
+ * A dsh row's `path` is its USAGE file, not its transcript (lib/usage-ledger/dsh-read.js).
+ *
  * @param {object} coreDb an open READONLY core handle (the read pool's flip-aware routed handle)
  * @param {{after?: string, limit?: number}} [options]
  * @returns {{sources: Array<{provider: string, session_id: string, path: string, size: number|null,
@@ -657,10 +667,11 @@ function readSourceCatalog(coreDb, { after = '', limit = SOURCE_CATALOG_DEFAULT_
     SELECT a.agent_session_id AS session_id,
            lower(COALESCE(a.provider, '')) AS provider,
            a.jsonl_path AS path,
+           ${cols.has('ctm_session_id') ? 'a.ctm_session_id' : 'NULL'} AS ctm_session_id,
            ${cols.has('file_size') ? 'a.file_size' : 'NULL'} AS size,
            ${cols.has('modified_at') ? 'a.modified_at' : 'NULL'} AS modified_at
       FROM agent_sessions a
-     WHERE lower(COALESCE(a.provider, '')) IN ('claude', 'codex')
+     WHERE lower(COALESCE(a.provider, '')) IN ('claude', 'codex', 'dsh')
        AND COALESCE(a.jsonl_path, '') != ''
        AND a.agent_session_id > @after
      ORDER BY a.agent_session_id
@@ -669,16 +680,14 @@ function readSourceCatalog(coreDb, { after = '', limit = SOURCE_CATALOG_DEFAULT_
   const hasMore = rows.length > effective;
   const kept = hasMore ? rows.slice(0, effective) : rows;
   const last = kept[kept.length - 1];
-  return {
-    sources: kept.map((row) => ({
-      provider: row.provider,
-      session_id: row.session_id == null ? '' : String(row.session_id),
-      path: row.path == null ? '' : String(row.path),
-      size: numberOrNull(row.size),
-      modified_at: textOrNull(row.modified_at),
-    })),
-    next: hasMore && last ? String(last.session_id) : null,
-  };
+  const sources = kept.map((row) => (row.provider === 'dsh' ? dshCatalogSource(row) : {
+    provider: row.provider,
+    session_id: row.session_id == null ? '' : String(row.session_id),
+    path: row.path == null ? '' : String(row.path),
+    size: numberOrNull(row.size),
+    modified_at: textOrNull(row.modified_at),
+  })).filter(Boolean);
+  return { sources, next: hasMore && last ? String(last.session_id) : null };
 }
 
 // A reported row's model_usage_json is written by the ingester; a torn or absent value reads

package/template/coding-task-manager/lib/usage-ledger/schema.js

@@ -15,7 +15,7 @@
 
 const { createMigrationRunner, pragmaVersionStore } = require('../../../shared/db-migration-runner');
 
-const USAGE_LEDGER_SCHEMA_VERSION = 8;
+const USAGE_LEDGER_SCHEMA_VERSION = 9;
 
 // The complete v1 schema, in one place. Each statement is idempotent
 // (IF NOT EXISTS) so a re-run of the baseline against a partially-created file
@@ -348,6 +348,62 @@ function createV8(db) {
   `);
 }
 
+// v9 (deepseek-harness-acp-agent WP-9, design D-19 / §9b L-3): `usage_files.provider` must admit
+// 'dsh'. D-19 gives dsh spend a source of its own -- the model proxy appends one row per completed
+// lead request to `<dataDir>/dsh-usage/<ctmSessionId>.jsonl` -- and the ledger ingests that file
+// under `provider='dsh'`, which the v1 CHECK `provider IN ('claude','codex')` refuses by SQLite
+// itself. SQLite cannot ALTER a CHECK, so the table is REBUILT: rename, recreate with the widened
+// CHECK, copy every row and every column, drop the staging table. v1 is left untouched: it stays the
+// published record of the schema IT created.
+//
+// Idempotence is decided by the SCHEMA, never by the version counter: a table whose sqlite_master.sql
+// already admits 'dsh' is left byte-for-byte alone. So a fresh file (the runner's isFresh path runs
+// the whole baseline, v9 included), a restored snapshot, and a file that already took this step all
+// converge on the same shape, and a re-run of the ladder body writes nothing.
+//
+// The recreate text is the table's OWN stored DDL with only the provider CHECK widened, so no column,
+// default, ordinal position or other constraint can drift from what the database already has. Copying
+// by position is what makes that mandatory, and `usage_files.file_id` is an INTEGER PRIMARY KEY
+// (rowid alias), so the copy preserves every id `usage_calls.source_file_id` already points at.
+//
+// The v9 step writes DDL only: nothing here inserts a 'dsh' row.
+const DSH_USAGE_FILES_TABLE = 'usage_files';
+// The exact v1 text of the provider CHECK. v1 is frozen, so this literal is stable; a table whose DDL
+// does not match it is refused rather than silently rebuilt with a guessed shape.
+const PROVIDER_CHECK = "CHECK(provider IN ('claude','codex'))";
+const PROVIDER_CHECK_DSH = "CHECK(provider IN ('claude','codex','dsh'))";
+
+function tableSql(db, table) {
+  const row = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
+  return row && typeof row.sql === 'string' ? row.sql : null;
+}
+
+// The EXPLICIT indexes of a table, in creation order. A PRIMARY KEY's implicit autoindex has sql =
+// NULL and must never be recreated by name, so it is filtered out. Captured BEFORE the rename, while
+// each index's SQL still names the real table: ALTER TABLE RENAME would rewrite that reference to the
+// staging name, and the DROP of the staging table takes the indexes with it.
+function tableIndexes(db, table) {
+  return db.prepare("SELECT name, sql FROM sqlite_master WHERE type = 'index' AND tbl_name = ? AND sql IS NOT NULL").all(table)
+    .map((row) => ({ name: row.name, sql: row.sql }));
+}
+
+function createV9(db) {
+  const sql = tableSql(db, DSH_USAGE_FILES_TABLE);
+  if (!sql) return;                      // no such table: nothing to widen
+  if (sql.includes("'dsh'")) return;     // already widened: idempotent on schema
+  const widened = sql.split(PROVIDER_CHECK).join(PROVIDER_CHECK_DSH);
+  if (widened === sql) {
+    throw new Error(`v9: ${DSH_USAGE_FILES_TABLE} has no claude/codex provider CHECK to widen`);
+  }
+  const staging = `${DSH_USAGE_FILES_TABLE}__v9`;
+  const indexes = tableIndexes(db, DSH_USAGE_FILES_TABLE);
+  db.exec(`ALTER TABLE ${DSH_USAGE_FILES_TABLE} RENAME TO ${staging}`);
+  db.exec(widened);
+  db.exec(`INSERT INTO ${DSH_USAGE_FILES_TABLE} SELECT * FROM ${staging}`);
+  db.exec(`DROP TABLE ${staging}`);
+  for (const index of indexes) db.exec(index.sql);
+}
+
 // Built lazily on first use so merely requiring this module has no side effects
 // (no module-level runner construction, no DDL, no env reads).
 let _runner = null;
@@ -370,6 +426,7 @@ function runner() {
         6: { up: createV6, label: 'v6 delegation edges' },
         7: { up: createV7, label: 'v7 delegation launch attempts' },
         8: { up: createV8, label: 'v8 claude re-read snapshot' },
+        9: { up: createV9, label: 'v9 dsh provider' },
       },
       baseline: (db) => {
         createV1(db);
@@ -380,6 +437,9 @@ function runner() {
         createV6(db);
         createV7(db);
         createV8(db);
+        // The baseline must produce the FULL current shape: for a fresh file this widens the v1
+        // provider CHECK in place (the table is empty, so the rebuild is a no-op on data).
+        createV9(db);
       },
       versionStore: pragmaVersionStore(),
     });

package/template/coding-task-manager/lib/usage-ledger/task-coordinator.js

@@ -3,6 +3,8 @@
 // One lifecycle-owned background round, driven by the existing client's hint tick. No interval,
 // transcript reads or model call on the configuration/status path.
 const { applyJudgeAnswer, JUDGE_QUESTIONS } = require('./task-grouping');
+// D-2: the ONE model-id rule (docs/lead-model-id-rule-at-tilde-prefix-2026-10-28.html §5).
+const { isValidOverrideModel } = require('../model-id-rule');
 const PROBE_INTERVAL_MS = 5000;
 const STATUS_TIMEOUT_MS = 2000;
 const DECISION_TIMEOUT_MS = 5000;
@@ -12,12 +14,12 @@ const BACKOFF_MS = 60000;
 // maker policy. Validated here (the ONE place) so the coordinator snapshot and the
 // /api/usage/task-grouping/status reader cannot disagree about what is safe to publish.
 const ROUTE_PROVIDER_ID_RE = /^[A-Za-z0-9._:@+-]{1,160}$/;
-const ROUTE_MODEL_ID_RE = /^[~A-Za-z0-9._:\/@+-]{1,160}$/;
 const ROUTE_POLICIES = new Set(['auto', 'direct', 'portkey']);
 function routeDetail(json) {
   return {
     provider_id: typeof json?.provider_id === 'string' && ROUTE_PROVIDER_ID_RE.test(json.provider_id) ? json.provider_id : null,
-    model_id: typeof json?.model_id === 'string' && ROUTE_MODEL_ID_RE.test(json.model_id) ? json.model_id : null,
+    // D-2: the ONE model-id rule (it also refuses a leading dash, which the forked rule admitted).
+    model_id: typeof json?.model_id === 'string' && isValidOverrideModel(json.model_id) ? json.model_id : null,
     policy: ROUTE_POLICIES.has(json?.policy) ? json.policy : null,
   };
 }