typeclaw 0.2.0 → 0.3.1

package/src/skills/typeclaw-memory/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: typeclaw-memory
-description: Use this skill whenever the user asks what you remember, what you forgot, what you dreamed, why a fact is or isn't in your memory, when memory consolidation happens, or whenever you are about to read or write `MEMORY.md`, anything under `memory/`, or `memory/skills/`. Triggers include "what do you remember", "do you remember X", "forget that", "what did you dream", "when do you dream next", "why did you forget X", "edit MEMORY.md", "add to memory", "your daily streams", "memory-logger", "dreaming", "muscle memory", or any mention of `memory.idleMs` / `memory.dreaming.schedule` in `typeclaw.json`. Read it before you touch any memory file — `MEMORY.md` and `memory/yyyy-MM-dd.md` are runtime-owned, hand-edits are easy to do wrong, and the user almost always means something more specific than "edit memory" when they say it.
+description: Use this skill whenever the user asks what you remember, what you forgot, what you dreamed, why a fact is or isn't in your memory, when memory consolidation happens, or whenever you are about to read or write `MEMORY.md`, anything under `memory/`, or `memory/skills/`. Triggers include "what do you remember", "do you remember X", "forget that", "what did you dream", "when do you dream next", "why did you forget X", "edit MEMORY.md", "add to memory", "your daily streams", "memory-logger", "dreaming", "muscle memory", or any mention of `memory.idleMs` / `memory.dreaming.schedule` in `typeclaw.json`. Read it before you touch any memory file — `MEMORY.md` and `memory/yyyy-MM-dd.jsonl` are runtime-owned, hand-edits are easy to do wrong, and the user almost always means something more specific than "edit memory" when they say it.
 ---
 
 # typeclaw-memory
 
-You have a two-stage memory system, owned by the bundled `memory` plugin (auto-loaded on every TypeClaw agent — there is no `plugins[]` entry to add and no opt-out). Daily observations flow into `memory/yyyy-MM-dd.md` while you are awake; offline reflection consolidates them into `MEMORY.md` and may distill repeated procedures into muscle-memory skills under `memory/skills/`. Both stages are run by subagents the runtime spawns on its own — not tools you call directly.
+You have a two-stage memory system, owned by the bundled `memory` plugin (auto-loaded on every TypeClaw agent — there is no `plugins[]` entry to add and no opt-out). Daily observations flow into `memory/yyyy-MM-dd.jsonl` while you are awake; offline reflection consolidates them into `MEMORY.md` and may distill repeated procedures into muscle-memory skills under `memory/skills/`. Both stages are run by subagents the runtime spawns on its own — not tools you call directly.
 
 This skill exists so you can answer the user's questions about your own memory honestly and so you do not corrupt it by hand-editing.
 
@@ -18,7 +18,7 @@ After every prompt completes, the runtime fires the `session.idle` hook. The mem
 The memory-logger reads:
 
 1. `MEMORY.md` (long-term memory)
-2. The current `memory/yyyy-MM-dd.md` daily stream
+2. The current `memory/yyyy-MM-dd.jsonl` daily stream
 3. The transcript of the parent session past a watermark (the `entry=` value of the last fragment or watermark marker for that session)
 
 It writes zero or more **fragments** to today's stream, plus a watermark marker so the next run knows where to resume. It writes nothing else, and it cannot run shell commands or edit existing content (its only tools are `read` and a custom `append`-only file tool — append never truncates, and a leading `\n` is auto-inserted if the existing file did not end in one).
@@ -43,9 +43,9 @@ The dreaming subagent runs on cron, configured under `memory.dreaming.schedule`
 When dreaming fires, it reads:
 
 1. `MEMORY.md`
-2. The **undreamed tail** of every `memory/yyyy-MM-dd.md` (the runtime tells it the exact line range — earlier lines are already consolidated into `MEMORY.md` and must NOT be re-read)
+2. The **undreamed fragments** of every `memory/yyyy-MM-dd.jsonl` (the runtime tells it which fragment ids are new — fragments whose ids are already in `memory/.dreaming-state.json#dreamedThrough[date].dreamedIds` have been consolidated and must NOT be re-cited)
 
-It rewrites `MEMORY.md` with the merged result, advances the per-day watermark in `memory/.dreaming-state.json`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, then commits the snapshot with a message shaped like `dream: <summary> <emoji>` — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`. The summary is derived from the staged diff (line additions in daily streams, newly-added skills, etc.), and the emoji is a random pick from a small thematic pool. After the commit, the runtime sets the `skip-worktree` index flag on the tracked memory artifacts so the user's `git status` and `git diff` stay clean. The flag is cleared and re-applied around every commit.
+It rewrites `MEMORY.md` with the merged result, advances the per-day dreamed-id set in `memory/.dreaming-state.json`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, **compacts the touched daily streams** (drops superseded watermarks per source and fragments that are in `dreamedIds` but not cited from `MEMORY.md`), then commits the snapshot with a message shaped like `dream: <summary> <emoji>` — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`. The summary is derived from the staged diff (line additions in daily streams, newly-added skills, etc.), and the emoji is a random pick from a small thematic pool. After the commit, the runtime sets the `skip-worktree` index flag on the tracked memory artifacts so the user's `git status` and `git diff` stay clean. The flag is cleared and re-applied around every commit.
 
 The dreaming subagent has only three tools: `read`, `write`, `ls`. No `bash`. No `edit`. It cannot run shell commands.
 
@@ -58,17 +58,17 @@ The dreaming subagent has only three tools: `read`, `write`, `ls`. No `bash`. No
 <conclusion paragraph in dreaming's own words>
 
 fragments:
-- memory/yyyy-MM-dd:<line>-<line>
-- memory/yyyy-MM-dd:<line>-<line>
+- memory/yyyy-MM-dd#<fragment-id>
+- memory/yyyy-MM-dd#<fragment-id>
 
 ## <topic>
 <conclusion paragraph>
 
 fragments:
-- memory/yyyy-MM-dd:<line>-<line>
+- memory/yyyy-MM-dd#<fragment-id>
 ```
 
-The first line is always `# Memory`. Topics are level-2 headings. Every topic cites the source fragments by `memory/yyyy-MM-dd:<line>-<line>` so any claim is traceable back to the daily stream entry that justified it.
+The first line is always `# Memory`. Topics are level-2 headings. Every topic cites the source fragments by `memory/yyyy-MM-dd#<uuidv7>` (the full id from the fragment event's `id` field) so any claim is traceable back to the daily stream entry that justified it. Citations are id-based, not line-based, so daily streams can be compacted between dreaming runs without invalidating prior references.
 
 If the undreamed tails contain only watermarks, or every new fragment is already represented in `MEMORY.md`, dreaming **does nothing** and exits without writing. The watermark advances either way. "No-op dreaming" is a normal outcome, not a failure.
 
@@ -77,7 +77,7 @@ If the undreamed tails contain only watermarks, or every new fragment is already
 Core's `createResourceLoader` appends a `# Memory` section as the LAST block of your system prompt (after `gitNudge`) by calling `loadMemory`. It is pinned to the cache-suffix end so growth in the daily stream invalidates only the memory section itself, not the skills/tools/history above. The section contains:
 
 - `MEMORY.md` (truncated to 12 KB; if larger, the rest is dropped with a `[truncated]` marker)
-- The **undreamed tails** of each `memory/yyyy-MM-dd.md`, with bare watermark lines stripped (they are bookkeeping for the memory-logger, no signal for you)
+- The **undreamed tails** of each `memory/yyyy-MM-dd.jsonl`, with bare watermark lines stripped (they are bookkeeping for the memory-logger, no signal for you)
 
 Already-consolidated content is not injected twice — once a day's stream is fully dreamed, the loader drops it from the prompt entirely.
 
@@ -86,9 +86,9 @@ If `MEMORY.md` is missing, the section shows `[MISSING] Expected at: <path>`. If
 ## What you must not do
 
 - **Do not edit `MEMORY.md` directly.** It is dreaming-owned. The default system prompt says this verbatim. If you write to `MEMORY.md` from a normal session, your edit will survive only until the next dreaming run, which rewrites the file from scratch using the consolidation logic above. The user's intent is almost never "diff-edit `MEMORY.md`" — see "When the user asks ..." below for the right routings.
-- **Do not write to `memory/yyyy-MM-dd.md`.** Daily streams are memory-logger's territory. The runtime reads watermarks out of these files; a hand-edit in the wrong place silently corrupts the cursor. (`memory/` is gitignored at the agent level but force-committed by the dreaming snapshot — your hand-edit there will not look untracked, but it will still be a bug.)
+- **Do not write to `memory/yyyy-MM-dd.jsonl`.** Daily streams are memory-logger's territory. The runtime reads watermarks out of these files; a hand-edit in the wrong place silently corrupts the cursor. (`memory/` is gitignored at the agent level but force-committed by the dreaming snapshot — your hand-edit there will not look untracked, but it will still be a bug.)
 - **Do not write to `memory/skills/<name>/SKILL.md`.** That is the _muscle memory_ layer, owned exclusively by the dreaming subagent. The `typeclaw-skills` skill says the same thing from the skills-system angle; this skill says it from the memory angle. If you want a hand-authored skill, put it in `.agents/skills/` instead.
-- **Do not write to `memory/.dreaming-state.json`.** It is internal bookkeeping (per-day line counts already consolidated). On malformed input the plugin fails open with empty state, so a wrong edit causes one redundant re-consolidation, but it is still a sign you misunderstood the contract.
+- **Do not write to `memory/.dreaming-state.json`.** It is internal bookkeeping (per-day dreamed-id sets). On malformed input the plugin fails open with empty state, so a wrong edit causes one redundant re-consolidation, but it is still a sign you misunderstood the contract.
 - **Do not promise the user that an `idleMs` or `dreaming.schedule` change took effect just because you edited `typeclaw.json`.** Both fields are **restart-required** — the plugin reads them once at boot, and `reload` does not re-run plugin factories. Tell the user to run `typeclaw restart` (host stage).
 - **Do not invent fragments.** If you find yourself wanting to "seed" a memory by hand, that is a symptom of the previous rules — surface the fact in your reply (so the memory-logger captures it) instead of writing to memory yourself.
 - **Do not echo `[truncated]` or `[MISSING]` markers back at the user as if they were part of remembered content.** They are runtime annotations.
@@ -96,13 +96,13 @@ If `MEMORY.md` is missing, the section shows `[MISSING] Expected at: <path>`. If
 ## When the user asks "what do you remember?"
 
 1. Read `MEMORY.md`. Summarize at the topic level — do not dump the whole file unless asked. Cite specific topics by their level-2 headings.
-2. If relevant to the current task, also read the undreamed-tail of recent `memory/yyyy-MM-dd.md` files for fresh observations not yet consolidated. (Note: these are already in your prompt under `# Memory`, so usually you can just refer to them rather than re-reading.)
+2. If relevant to the current task, also read the undreamed-tail of recent `memory/yyyy-MM-dd.jsonl` files for fresh observations not yet consolidated. (Note: these are already in your prompt under `# Memory`, so usually you can just refer to them rather than re-reading.)
 3. If `MEMORY.md` is `[MISSING]` or `[EMPTY]`, say so plainly. The first dreaming run creates the file; if dreaming has never fired (e.g. no `memory.dreaming.schedule` configured, or fewer than ~24 hours since hatching), there is genuinely nothing yet.
 
 ## When the user asks "do you remember X?"
 
 1. Search `MEMORY.md` and recent daily streams for a fragment matching X.
-2. If you find one: say what you found and cite the source (the topic heading from `MEMORY.md`, or the fragment line range from the daily stream).
+2. If you find one: say what you found and cite the source (the topic heading from `MEMORY.md`, or the `memory/yyyy-MM-dd#<id>` citation from the daily stream).
 3. If you do not find one: say so plainly. **Do not invent a memory** to be helpful. The honest answer is "no, that is not in my memory" — the user can then decide whether to repeat the context now (which the memory-logger will pick up) or skip it.
 
 ## When the user asks "forget X" / "remove X from your memory"
@@ -125,7 +125,7 @@ Stay concrete. Use this map:
 | File / dir                      | What it is                                                                    | Who writes it                                                  | Tracked in git                                               |
 | ------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
 | `MEMORY.md`                     | Long-term memory, consolidated topics with fragment citations.                | Dreaming subagent (rewrites in full on each run).              | Yes (force-committed under `dream:` commits, skip-worktree). |
-| `memory/yyyy-MM-dd.md`          | Daily fragment streams. Append-only during the day.                           | Memory-logger subagent (one fragment ≈ one prompt completion). | Gitignored, but force-committed in the dreaming snapshot.    |
+| `memory/yyyy-MM-dd.jsonl`       | Daily fragment streams. Append-only during the day.                           | Memory-logger subagent (one fragment ≈ one prompt completion). | Gitignored, but force-committed in the dreaming snapshot.    |
 | `memory/skills/<name>/SKILL.md` | Muscle-memory skills distilled from recurring procedures.                     | Dreaming subagent only.                                        | Gitignored, force-committed in the dreaming snapshot.        |
 | `memory/.dreaming-state.json`   | Per-day watermarks (line counts already consolidated). Plain JSON, fail-open. | Dreaming subagent.                                             | Gitignored, force-committed in the dreaming snapshot.        |
 

package/src/usage/aggregate.ts

@@ -1,4 +1,5 @@
-import type { AssistantRow } from './scan'
+import type { AssistantRow, OriginKind } from './scan'
+import { ORIGIN_KINDS } from './scan'
 
 export type UsageTotals = {
   messageCount: number
@@ -18,13 +19,16 @@ export type SessionUsage = UsageTotals & {
   firstAt: number
   lastAt: number
   models: string[]
+  originKind: OriginKind
 }
+export type OriginUsage = UsageTotals & { originKind: OriginKind; sessionCount: number }
 
 export type Aggregation = {
   total: UsageTotals
   byDay: DailyUsage[]
   byModel: ModelUsage[]
   bySession: SessionUsage[]
+  byOrigin: OriginUsage[]
 }
 
 export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggregation> {
@@ -32,6 +36,7 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
   const byDay = new Map<string, DailyUsage & { _sessionIds: Set<string> }>()
   const byModel = new Map<string, ModelUsage>()
   const bySession = new Map<string, SessionUsage & { _modelSet: Set<string> }>()
+  const byOrigin = new Map<OriginKind, OriginUsage & { _sessionIds: Set<string> }>()
 
   for await (const row of rows) {
     addInto(total, row)
@@ -66,6 +71,7 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
       lastAt: row.timestamp,
       models: [],
       _modelSet: new Set<string>(),
+      originKind: row.originKind,
     }
     addInto(sessionBucket, row)
     sessionBucket.firstAt = Math.min(sessionBucket.firstAt, row.timestamp)
@@ -73,6 +79,17 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
     sessionBucket._modelSet.add(modelKey)
     sessionBucket.models = [...sessionBucket._modelSet]
     bySession.set(sessionKey, sessionBucket)
+
+    const originBucket = byOrigin.get(row.originKind) ?? {
+      ...emptyTotals(),
+      originKind: row.originKind,
+      sessionCount: 0,
+      _sessionIds: new Set<string>(),
+    }
+    addInto(originBucket, row)
+    originBucket._sessionIds.add(sessionKey)
+    originBucket.sessionCount = originBucket._sessionIds.size
+    byOrigin.set(row.originKind, originBucket)
   }
 
   return {
@@ -80,9 +97,21 @@ export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggr
     byDay: [...byDay.values()].map(({ _sessionIds: _, ...rest }) => rest).sort((a, b) => a.date.localeCompare(b.date)),
     byModel: [...byModel.values()].sort((a, b) => b.cost - a.cost),
     bySession: [...bySession.values()].map(({ _modelSet: _, ...rest }) => rest).sort((a, b) => b.cost - a.cost),
+    byOrigin: [...byOrigin.values()]
+      .map(({ _sessionIds: _, ...rest }) => rest)
+      .sort((a, b) => originSortIndex(a.originKind) - originSortIndex(b.originKind)),
   }
 }
 
+// Stable presentation order for the byOrigin table. Matches ORIGIN_KINDS so
+// the renderer doesn't need to know about ordering. 'unknown' is pinned last
+// because it represents legacy/malformed data the user probably cares about
+// least.
+function originSortIndex(kind: OriginKind): number {
+  const idx = (ORIGIN_KINDS as readonly OriginKind[]).indexOf(kind)
+  return idx === -1 ? Number.MAX_SAFE_INTEGER : idx
+}
+
 function emptyTotals(): UsageTotals {
   return { messageCount: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: 0 }
 }

package/src/usage/index.ts

@@ -4,8 +4,9 @@ import type { Aggregation } from './aggregate'
 import { aggregate } from './aggregate'
 import { scanAssistantRows } from './scan'
 
-export type { Aggregation, DailyUsage, ModelUsage, SessionUsage, UsageTotals } from './aggregate'
-export type { AssistantRow } from './scan'
+export type { Aggregation, DailyUsage, ModelUsage, OriginUsage, SessionUsage, UsageTotals } from './aggregate'
+export type { AssistantRow, OriginKind } from './scan'
+export { ORIGIN_KINDS } from './scan'
 
 export type UsageReport = {
   generatedAt: number

package/src/usage/report.ts

@@ -1,12 +1,13 @@
 import { styleText } from 'node:util'
 
-import type { ModelUsage, UsageTotals } from './aggregate'
+import type { ModelUsage, OriginUsage, UsageTotals } from './aggregate'
 import { formatCacheHitRate, formatCost, formatTokens, isoDay } from './format'
 import type { UsageReport } from './index'
+import type { OriginKind } from './scan'
 
 export type FormatOptions = {
   useColor?: boolean
-  view?: 'summary' | 'daily' | 'session' | 'models'
+  view?: 'summary' | 'daily' | 'session' | 'models' | 'origin'
   limit?: number
   // Terminal width hint used to size the elastic Item column. Omit to render
   // without truncation (tests, piped output where columns is undefined).
@@ -26,6 +27,8 @@ export function formatReport(report: UsageReport, opts: FormatOptions = {}): str
       return renderSessions(report, ctx, opts.limit ?? 20)
     case 'models':
       return renderModels(report, ctx, opts.limit)
+    case 'origin':
+      return renderOrigin(report, ctx)
   }
 }
 
@@ -58,12 +61,20 @@ function renderSummary(report: UsageReport, ctx: RenderCtx): string {
 
   if (aggregation.byDay.length > 0) {
     sections.push('')
+    const trend = renderDailyTrend(aggregation.byDay, ctx)
+    if (trend !== null) sections.push(trend, '')
     sections.push(header('By day (most recent first)', ctx))
     const recent = aggregation.byDay.slice(-7).reverse()
     const dayRows = recent.map((d) => ({ label: d.date, totals: d as UsageTotals }))
     sections.push(renderTotalsTable(dayRows, ctx, { total: totalOfRows(dayRows) }))
   }
 
+  if (aggregation.byOrigin.length > 0) {
+    sections.push('')
+    sections.push(header('By origin', ctx))
+    sections.push(renderOriginTable(aggregation.byOrigin, ctx))
+  }
+
   if (aggregation.byModel.length > 0) {
     sections.push('')
     sections.push(header('By model', ctx))
@@ -84,6 +95,79 @@ function renderSummary(report: UsageReport, ctx: RenderCtx): string {
   return sections.join('\n')
 }
 
+function renderOrigin(report: UsageReport, ctx: RenderCtx): string {
+  const sections: string[] = [sectionTitle('USAGE BY ORIGIN', report.agentDir, ctx)]
+  if (report.aggregation.byOrigin.length === 0) {
+    sections.push(dim('No assistant turns recorded yet.', ctx))
+    return sections.join('\n')
+  }
+  sections.push(renderOriginTable(report.aggregation.byOrigin, ctx))
+  return sections.join('\n')
+}
+
+// Single source of truth for the origin breakdown table used by both the
+// summary view and the dedicated `usage origin` subcommand. Matches the
+// column shape of renderTotalsTable's other callers (byDay, byModel) plus
+// one extra column for session count — deliberately plain numbers rather
+// than a proportional bar, since the Cost column already lets the eye sort
+// rows by spend and an extra "share of max" bar adds no information that
+// isn't already in the report.
+function renderOriginTable(byOrigin: readonly OriginUsage[], ctx: RenderCtx): string {
+  const rows = byOrigin.map((o) => ({
+    label: renderOriginLabel(o.originKind, ctx),
+    totals: o as UsageTotals,
+    extra: String(o.sessionCount),
+    extraTruncatable: false,
+  }))
+  return renderTotalsTable(rows, ctx, {
+    extraHeader: 'Sessions',
+    total: totalOfRows(rows),
+  })
+}
+
+// Glyph + colored label for each origin kind. The glyphs are chosen to be
+// instantly readable in a dense table: ▶ for TUI (interactive), ⏱ for cron
+// (time-triggered), # for channel (chat-room sigil), ↳ for subagent (child),
+// ? for unknown. ASCII fallbacks are not provided — the codebase already
+// requires unicode for `…` `●` `✓` etc. on other commands.
+function renderOriginLabel(kind: OriginKind, ctx: RenderCtx): string {
+  switch (kind) {
+    case 'tui':
+      return `${color('cyan', '▶', ctx)} ${'tui'}`
+    case 'cron':
+      return `${color('magenta', '⏱', ctx)} ${'cron'}`
+    case 'channel':
+      return `${color('green', '#', ctx)} ${'channel'}`
+    case 'subagent':
+      return `${color('yellow', '↳', ctx)} ${'subagent'}`
+    case 'unknown':
+      return `${dim('?', ctx)} ${dim('unknown', ctx)}`
+  }
+}
+
+// Sparkline trend across the full byDay range, scaled to the row's max cost.
+// Returns null when there are fewer than 2 days (a single point conveys no
+// trend information). The 8-level Unicode block scale `▁▂▃▄▅▆▇█` lets us
+// pack ~80 days into a one-line glance — wider than any table-based view
+// could fit at terminal widths under ~160 columns.
+const SPARK_GLYPHS = '▁▂▃▄▅▆▇█'
+
+function renderDailyTrend(byDay: readonly { date: string; cost: number }[], ctx: RenderCtx): string | null {
+  if (byDay.length < 2) return null
+  const costs = byDay.map((d) => d.cost)
+  const max = costs.reduce((m, c) => Math.max(m, c), 0)
+  if (max <= 0) return null
+  const spark = costs
+    .map((c) => {
+      const idx = Math.min(SPARK_GLYPHS.length - 1, Math.max(0, Math.round((c / max) * (SPARK_GLYPHS.length - 1))))
+      return SPARK_GLYPHS[idx]!
+    })
+    .join('')
+  const first = byDay[0]!.date
+  const last = byDay[byDay.length - 1]!.date
+  return `${dim('Trend (cost):', ctx)} ${color('cyan', spark, ctx)}  ${dim(`${first} → ${last}`, ctx)}`
+}
+
 function renderDaily(report: UsageReport, ctx: RenderCtx, limit: number | undefined): string {
   const days = limit !== undefined ? report.aggregation.byDay.slice(-limit) : report.aggregation.byDay
   if (days.length === 0) return dim('No usage in range.', ctx)
@@ -100,8 +184,9 @@ function renderSessions(report: UsageReport, ctx: RenderCtx, limit: number): str
   const rows = sessions.map((s) => {
     const firstModel = s.models[0]
     const extra = s.models.length > 1 ? `${s.models.length} models` : modelIdFromKey(firstModel)
+    const originGlyph = originGlyphOnly(s.originKind, ctx)
     return {
-      label: `${color('magenta', s.sessionId.slice(0, 12), ctx)}  ${dim(isoDay(s.firstAt), ctx)}`,
+      label: `${originGlyph}  ${color('magenta', s.sessionId.slice(0, 12), ctx)}  ${dim(isoDay(s.firstAt), ctx)}`,
       totals: s as UsageTotals,
       extra,
       extraTruncatable: s.models.length === 1,
@@ -113,6 +198,21 @@ function renderSessions(report: UsageReport, ctx: RenderCtx, limit: number): str
   ].join('\n')
 }
 
+function originGlyphOnly(kind: OriginKind, ctx: RenderCtx): string {
+  switch (kind) {
+    case 'tui':
+      return color('cyan', '▶', ctx)
+    case 'cron':
+      return color('magenta', '⏱', ctx)
+    case 'channel':
+      return color('green', '#', ctx)
+    case 'subagent':
+      return color('yellow', '↳', ctx)
+    case 'unknown':
+      return dim('?', ctx)
+  }
+}
+
 function renderModels(report: UsageReport, ctx: RenderCtx, limit: number | undefined): string {
   const models = limit !== undefined ? report.aggregation.byModel.slice(0, limit) : report.aggregation.byModel
   if (models.length === 0) return dim('No models in range.', ctx)

package/src/usage/scan.ts

@@ -1,6 +1,14 @@
 import { readdir } from 'node:fs/promises'
 import { join } from 'node:path'
 
+// Recognised origin kinds. Keep aligned with SessionOrigin's discriminator in
+// src/agent/session-origin.ts. The 'unknown' bucket catches sessions written
+// before origin stamping landed AND sessions whose session-meta line is
+// malformed or missing — surfacing them under one explicit label is more
+// honest than silently dropping them.
+export const ORIGIN_KINDS = ['tui', 'cron', 'channel', 'subagent', 'unknown'] as const
+export type OriginKind = (typeof ORIGIN_KINDS)[number]
+
 // Narrow projection: session files can grow into tens of MB on long-lived
 // agents, so we deliberately drop content/tool blocks before aggregation.
 export type AssistantRow = {
@@ -15,6 +23,7 @@ export type AssistantRow = {
   cacheWrite: number
   totalTokens: number
   cost: number
+  originKind: OriginKind
 }
 
 export type ScanOptions = {
@@ -66,6 +75,13 @@ async function* readSessionFile(file: string, opts: ScanOptions): AsyncGenerator
   }
   const decoder = new TextDecoder()
   let buf = ''
+  // First-stamp-wins per file. Once a `typeclaw.session-meta` custom entry
+  // pins the origin, later entries with the same customType are ignored —
+  // session-resume code paths may legitimately re-stamp on reopen, and the
+  // earliest one is the authoritative one for the session's first turn.
+  // Stays 'unknown' for legacy files (no stamp at all) so usage attribution
+  // surfaces them as a distinct bucket rather than dropping the rows.
+  const ctx: ParseCtx = { originKind: 'unknown', originPinned: false }
   try {
     for await (const chunk of stream) {
       buf += decoder.decode(chunk, { stream: true })
@@ -73,7 +89,7 @@ async function* readSessionFile(file: string, opts: ScanOptions): AsyncGenerator
       while (nl !== -1) {
         const line = buf.slice(0, nl)
         buf = buf.slice(nl + 1)
-        const row = parseLine(line, file, basename, opts)
+        const row = parseLine(line, file, basename, opts, ctx)
         if (row !== null) yield row
         nl = buf.indexOf('\n')
       }
@@ -86,17 +102,20 @@ async function* readSessionFile(file: string, opts: ScanOptions): AsyncGenerator
   // half-written record from a live writer is silently skipped (parseLine
   // returns null and does NOT warn for the tail).
   if (buf.length > 0) {
-    const row = parseLine(buf, file, basename, opts, { isTail: true })
+    const row = parseLine(buf, file, basename, opts, ctx, { isTail: true })
     if (row !== null) yield row
   }
 }
 
+type ParseCtx = { originKind: OriginKind; originPinned: boolean }
+
 function parseLine(
   line: string,
   file: string,
   basename: string,
   opts: ScanOptions,
-  ctx: { isTail?: boolean } = {},
+  ctx: ParseCtx,
+  flags: { isTail?: boolean } = {},
 ): AssistantRow | null {
   const trimmed = line.trim()
   if (trimmed === '') return null
@@ -106,7 +125,18 @@ function parseLine(
     entry = JSON.parse(trimmed)
   } catch {
     // Silently skip the trailing tail: a live writer may be mid-append.
-    if (ctx.isTail !== true) opts.onWarn?.(`skipping malformed JSONL line in ${basename}`)
+    if (flags.isTail !== true) opts.onWarn?.(`skipping malformed JSONL line in ${basename}`)
+    return null
+  }
+
+  if (isSessionMetaCustomEntry(entry)) {
+    if (!ctx.originPinned) {
+      const kind = entry.data.origin.kind
+      if ((ORIGIN_KINDS as readonly string[]).includes(kind)) {
+        ctx.originKind = kind as OriginKind
+        ctx.originPinned = true
+      }
+    }
     return null
   }
 
@@ -134,9 +164,34 @@ function parseLine(
     cacheWrite: numberOrZero(u.cacheWrite),
     totalTokens: numberOrZero(u.totalTokens),
     cost: numberOrZero(u.cost?.total),
+    originKind: ctx.originKind,
   }
 }
 
+// Pi-coding-agent persists `appendCustomEntry(customType, data)` calls as
+// `{type:"custom", customType, data, id, parentId, timestamp}` lines. We
+// stamp our origin block with customType `typeclaw.session-meta` (constant
+// kept in src/agent/session-meta.ts; duplicated as a literal here to keep
+// the usage subsystem free of agent-stack imports — a Grep across the repo
+// is the chosen drift guard).
+type SessionMetaCustomEntry = {
+  type: 'custom'
+  customType: 'typeclaw.session-meta'
+  data: { origin: { kind: string } }
+}
+
+function isSessionMetaCustomEntry(value: unknown): value is SessionMetaCustomEntry {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (v.type !== 'custom') return false
+  if (v.customType !== 'typeclaw.session-meta') return false
+  if (typeof v.data !== 'object' || v.data === null) return false
+  const d = v.data as Record<string, unknown>
+  if (typeof d.origin !== 'object' || d.origin === null) return false
+  const o = d.origin as Record<string, unknown>
+  return typeof o.kind === 'string'
+}
+
 type MessageEntry = { type: 'message'; message: { role: string; [k: string]: unknown } }
 type AssistantMessageShape = {
   role: 'assistant'