@jbarket/loomai 0.5.0 → 0.7.0

package/dist/backends/types.d.ts

@@ -5,6 +5,19 @@
  * storage backend. Any backend that implements MemoryBackend can be
  * swapped in; v0.3.1 ships SqliteVecBackend as the single opinion.
  */
+/**
+ * How a memory was sourced — mirrors the knowledge wing's sourcing field.
+ * Displayed at injection time so readers can calibrate confidence.
+ *
+ * - `observed`  — directly witnessed by this body: measured, tested, read from source.
+ * - `relayed`   — learned from another person/body: conversation, letter, episode.
+ * - `inferred`  — AI-generated reasoning/synthesis: extrapolation, pattern-matching.
+ *                 Treat with appropriate skepticism — not ground truth.
+ * - `system`    — auto-written by the harness (episode fallback, lane output, etc.).
+ */
+export type MemorySourcing = 'observed' | 'relayed' | 'inferred' | 'system';
+export type { MemoryScope } from './scope.js';
+import type { MemoryScope } from './scope.js';
 export interface MemoryInput {
     category: string;
     title: string;
@@ -13,6 +26,29 @@ export interface MemoryInput {
     metadata?: Record<string, unknown>;
     /** Optional time-to-live. Parsed durations like "7d", "30d", or "permanent". */
     ttl?: string;
+    /**
+     * How this memory was sourced. Displayed at injection so the reader can
+     * calibrate confidence — 'inferred' flags AI-generated reasoning that should
+     * not be treated as ground truth.
+     */
+    sourcing?: MemorySourcing;
+    /**
+     * Free-form origin: surface, body, session, or person. E.g. "wake:w-74fccc
+     * 2026-09-07", "Jonathan, Discord #loom", "lane:letters". For episodes,
+     * prefer metadata.where (already conventional); this carries additional detail.
+     */
+    provenance?: string;
+    /**
+     * Explicit scope override — 'project' (only recallable while scoped to
+     * this memory's project) or 'global' (recallable regardless of project).
+     * Omit to take the category default (see backends/scope.ts): 'user' and
+     * 'reference' default global, everything else defaults project when a
+     * project is attached, global when it isn't. Set this explicitly to flag
+     * a genuinely cross-project fact learned in a project context — e.g. a
+     * git/security/tool-workflow practice that happened to surface while
+     * working on one project but applies everywhere (t-337).
+     */
+    scope?: MemoryScope;
 }
 export interface MemoryRef {
     ref: string;
@@ -66,13 +102,38 @@ export interface MemoryMatch {
     project?: string;
     created: string;
     content: string;
+    /**
+     * Final ranking score for this result's position in the returned list.
+     * Equals `similarity` unless MMR re-ranking (recall's `diversity` > 0)
+     * traded this pick off against ones already selected — in that case this
+     * is the blended score (λ·similarity − (1−λ)·max similarity-to-selected)
+     * that actually placed it, not its raw similarity. See `similarity` for
+     * the pre-MMR number alongside it (t-337a; modeled on MemoriLabs/Memori's
+     * FactSearchResult.{similarity, rank_score} split).
+     */
     relevance: number;
+    /** Raw cosine similarity (1 − distance) to the query, before any MMR re-ranking. */
+    similarity: number;
+    /** Effective scope this memory was recalled under — see backends/scope.ts (t-337b). */
+    scope: MemoryScope;
     /** ISO timestamp of last recall hit, if tracked */
     lastAccessed?: string;
     /** TTL value if set (e.g. "7d", "permanent") */
     ttl?: string;
     /** ISO timestamp when this memory expires, if TTL is set */
     expiresAt?: string;
+    /** Sourcing tier — how the memory was produced. Null on legacy records. */
+    sourcing?: MemorySourcing;
+    /** Free-form origin text (surface / person / session). Null on legacy records. */
+    provenance?: string;
+    /**
+     * Evidence-backed confidence (0.3-0.9), feedback memories only (t-338).
+     * Decayed toward neutral by category half-life — see salience.ts
+     * decayedConfidence(). Undefined for non-feedback memories.
+     */
+    confidence?: number;
+    /** Number of observations (creation + confirm/contradict) behind `confidence`. */
+    evidenceCount?: number;
 }
 export interface ForgetInput {
     /** Direct reference (category/filename) for single deletion */
@@ -97,6 +158,13 @@ export interface UpdateInput {
     content?: string;
     /** Metadata fields to add or update */
     metadata?: Record<string, unknown>;
+    /**
+     * Record an observation against this memory's confidence (feedback
+     * memories only, t-338): 'confirm' raises it, 'contradict' lowers it.
+     * Computed in code (see salience.ts applyObservation) — never a prompt.
+     * Ignored on non-feedback memories.
+     */
+    observation?: 'confirm' | 'contradict';
 }
 export interface ForgetResult {
     /** Refs that were successfully deleted */
@@ -133,6 +201,10 @@ export interface UpdateResult {
     ref?: string;
     /** Id of the body snapshot taken before content was overwritten (if any). */
     snapshotId?: number;
+    /** Raw (undecayed) confidence after applying `observation`, when one was given. */
+    confidence?: number;
+    /** Evidence count after applying `observation`, when one was given. */
+    evidenceCount?: number;
 }
 /** Revision listing entry — metadata only, no body payload. */
 export interface MemoryRevisionMeta {
@@ -173,8 +245,31 @@ export interface MemorySupersededResult {
     /** True when old_ref was archived by this call; false if already archived. */
     archived: boolean;
 }
+export interface MemoryMergeInput {
+    /** Refs of the losing memories to fold into the target (all must be active). */
+    source_refs: string[];
+    /** Ref of the canonical memory that survives the merge (must already exist, active). */
+    target_ref: string;
+    /** Optional note about this merge, stored in supersession tombstones on the losers. */
+    note?: string;
+    /** Hard-delete losers after archiving/superseding them (default false). */
+    hard_delete_losers?: boolean;
+    /** Append loser bodies to the target content under section markers (default false). */
+    append_loser_bodies?: boolean;
+}
+export interface MemoryMergeResult {
+    target_ref: string;
+    sources_merged: number;
+    /** Target's times_seen after summing in each merged source's count. */
+    times_seen: number;
+    losers: {
+        ref: string;
+        title: string;
+        content: string;
+    }[];
+}
 export interface PruneResult {
-    /** Memories that were deleted because their TTL expired */
+    /** Memories that were archived (moved to archive tier) because their TTL expired */
     expired: string[];
     /** Memories that haven't been accessed within the stale threshold */
     stale: string[];
@@ -190,6 +285,14 @@ export interface MemoryEntry {
     category: string;
     project?: string;
     created: string;
+    /** Sourcing tier — how the memory was produced. Null on legacy records. */
+    sourcing?: MemorySourcing;
+    /** Free-form origin text (surface / person / session). Null on legacy records. */
+    provenance?: string;
+    /** Decayed confidence (feedback memories only, t-338). */
+    confidence?: number;
+    /** Observation count behind `confidence`. */
+    evidenceCount?: number;
 }
 export interface FindSimilarInput {
     /** Anchor on an existing memory's embedding. Exactly one of `ref`/`text`. */
@@ -239,7 +342,7 @@ export interface AuditReport {
     stale: AuditStaleEntry[];
     /** Pairs of memories whose vector similarity ≥ `similarityThreshold`. */
     duplicates: DuplicatePair[];
-    /** Memories whose TTL has expired (would be removed by `prune`). */
+    /** Memories whose TTL has expired (would be archived by `prune`). */
     expired: string[];
 }
 export interface MemoryBackend {
@@ -269,6 +372,13 @@ export interface MemoryBackend {
     restoreRevision(input: MemoryRevisionRestoreInput): Promise<MemoryRevisionRestoreResult>;
     /** Archive old_ref with a tombstone and record that new_ref supersedes it. */
     supersede(input: MemorySupersededInput): Promise<MemorySupersededResult>;
+    /**
+     * Consolidate 2+ memories into one canonical row. Acts on an audit()
+     * duplicate-finding: sources are archived with a supersession pointer to
+     * the target (parity with supersede(), but N:1), times_seen is summed
+     * onto the target, and bodies are optionally concatenated.
+     */
+    mergeMemories(input: MemoryMergeInput): Promise<MemoryMergeResult>;
     /** Release the underlying store handle. Cached backends evict on close. */
     close(): void;
 }
@@ -291,6 +401,14 @@ export interface KnowledgePageInput {
     verified_at?: string;
     /** The version/date the claims are valid as-of, e.g. "Syntakt OS 1.21" or "as of 2026-05". */
     freshness_anchor?: string;
+    /**
+     * Machine-readable SLA class. When omitted, derived automatically: a
+     * version-anchored page (freshness_anchor matches /v?\d+\.\d+/) → 'software';
+     * device-domain page (domain starts with 'music/gear' or 'monitor/hardware') →
+     * 'device'; all others → 'default'. SLAs: device=7d, software=14d, default=30d.
+     * Pass explicitly to override the derived value.
+     */
+    sla_class?: 'device' | 'software' | 'default';
     citations?: KnowledgeCitationInput[];
     /**
      * How `body` combines with an existing page on upsert.
@@ -308,6 +426,15 @@ export interface KnowledgePageInput {
      * (e.g. "v2", "2026-08-19", "t-81"). Preserved across upserts when omitted.
      */
     version?: string;
+    /**
+     * Caller's loom identity, resolved server-side (never a free-text tool
+     * argument — that would let any caller claim any authorship). Stamped as
+     * pages.author only on creation (the identity that wrote v1 — never
+     * overwritten by later upserts) and as page_revisions.actor on any
+     * snapshot this call produces. Omitted means "unknown" (legacy direct
+     * callers, tests) rather than a hard requirement.
+     */
+    actor?: string;
 }
 export interface KnowledgeCitationInput {
     claim: string;
@@ -334,10 +461,22 @@ export interface KnowledgePage {
     verified_at?: string | null;
     /** The version/date the claims are valid as-of, e.g. "Syntakt OS 1.21". */
     freshness_anchor?: string | null;
+    /**
+     * Machine-readable SLA class: 'device' (7d), 'software' (14d), 'default' (30d).
+     * Derived from freshness_anchor shape and domain on write; may be overridden
+     * explicitly via KnowledgePageInput.sla_class.
+     */
+    sla_class: string;
     /** ours/ class: who created or last owned this artifact (e.g. "art", "jonathan"). */
     created_by?: string | null;
     /** ours/ class: artifact version or revision tag (e.g. "v2", "2026-08-19"). */
     version?: string | null;
+    /**
+     * Identity that wrote v1 of this page — set once at creation, never
+     * changed by later upserts. Null for pages created before this column
+     * existed, or written by a direct backend caller that omitted actor.
+     */
+    author?: string | null;
 }
 export interface KnowledgeCitation {
     id: number;
@@ -369,6 +508,19 @@ export interface KnowledgeQueryInput {
      * never-verified pages first. Overrides the default hit-count ordering.
      */
     sortByVerified?: boolean;
+    /**
+     * Who is reading (t-677). When stampAccess fires, this identity's row in
+     * knowledge_access is upserted alongside the shared pages.hit_count /
+     * last_accessed aggregate. Defaults to 'unknown' when omitted — callers
+     * that care about attribution should always pass the acting identity.
+     */
+    identity?: string;
+}
+/** One reader's access stats on a page (t-677 per-identity attribution). */
+export interface KnowledgeAccessStat {
+    identity: string;
+    hit_count: number;
+    last_accessed: string | null;
 }
 export interface KnowledgePageRef {
     uuid: string;
@@ -481,14 +633,41 @@ export interface KnowledgeVerifyInput {
     freshness_anchor?: string;
     /** Optional note — appended to the body as a "## Verification — <date>" section (single-page mode only). */
     note?: string;
+    /**
+     * Caller's loom identity, resolved server-side (never a free-text tool
+     * argument). Recorded as verifications.verifier for every page stamped
+     * by this call. Omitted means "unknown" (legacy direct callers, tests).
+     */
+    verifier?: string;
+    /** What the verification found. Defaults to 'confirmed' (the claims still hold). */
+    outcome?: 'confirmed' | 'stale' | 'corrected';
+    /** Whether the verifier actually checked the page's citations against their sources. Defaults to false. */
+    citation_checked?: boolean;
 }
 export interface KnowledgeVerifyResult {
     verified: number;
     slugs: string[];
+    /** The verification time recorded in the audit trail. */
     verified_at: string;
+    /**
+     * True when pages.verified_at was advanced to `verified_at`. False for an
+     * outcome of 'stale' — a failed verification is audited but does not
+     * renew the page's successful-freshness stamp.
+     */
+    stamped: boolean;
     /** True when a note section was appended to the body. */
     noted: boolean;
 }
+/** A verification record — who verified a page, when, and what they found. */
+export interface KnowledgeVerificationRecord {
+    id: number;
+    page_id: number;
+    /** Resolved loom identity of the verifier; null for pre-attribution rows. */
+    verifier: string | null;
+    verified_at: string;
+    outcome: string;
+    citation_checked: boolean;
+}
 /** Revision listing entry — metadata only, no body payload. */
 export interface KnowledgeRevisionMeta {
     id: number;
@@ -499,6 +678,8 @@ export interface KnowledgeRevisionMeta {
     op: string;
     replaced_at: string;
     body_length: number;
+    /** Resolved loom identity that performed the action, null for pre-attribution rows. */
+    actor: string | null;
 }
 export interface KnowledgeRevision extends Omit<KnowledgeRevisionMeta, 'body_length'> {
     body: string;
@@ -506,6 +687,8 @@ export interface KnowledgeRevision extends Omit<KnowledgeRevisionMeta, 'body_len
 export interface KnowledgeRevisionRestoreInput {
     slug: string;
     revision_id: number;
+    /** Caller's loom identity, resolved server-side — recorded on the snapshot this restore takes of the displaced body. */
+    actor?: string;
 }
 export interface KnowledgeRevisionRestoreResult {
     slug: string;
@@ -527,9 +710,14 @@ export interface KnowledgePurgeResult {
 export interface KnowledgeBackend {
     /** Upsert an entity page by slug; create or append. */
     writePage(input: KnowledgePageInput): Promise<KnowledgeWriteResult>;
-    /** Get a single page by slug. opts.stampAccess marks the fetch as a real read (last_accessed / hit_count). */
+    /**
+     * Get a single page by slug. opts.stampAccess marks the fetch as a real
+     * read (last_accessed / hit_count); opts.identity attributes that read
+     * to a reader (t-677) — defaults to 'unknown' when omitted.
+     */
     getPage(slug: string, opts?: {
         stampAccess?: boolean;
+        identity?: string;
     }): Promise<KnowledgePageWithCitations | null>;
     /** List pages with optional filters. */
     listPages(input?: KnowledgeQueryInput): Promise<KnowledgePageWithCitations[]>;
@@ -551,12 +739,24 @@ export interface KnowledgeBackend {
     purgePages(input: KnowledgePurgeInput): Promise<KnowledgePurgeResult>;
     /** Stamp verified_at / freshness_anchor without touching the body (optional appended note in single-page mode). */
     verifyPages(input: KnowledgeVerifyInput): Promise<KnowledgeVerifyResult>;
+    /** List verification records for a page, newest first. */
+    getVerifications(slug: string): Promise<KnowledgeVerificationRecord[]>;
     /** List body snapshots for a page, newest first. Metadata only — no body payloads. */
     listRevisions(slug: string): Promise<KnowledgeRevisionMeta[]>;
     /** Fetch one revision including its full body. */
     getRevision(revisionId: number): Promise<KnowledgeRevision | null>;
     /** Restore a revision's body onto its page; the displaced body is snapshotted first. */
     restoreRevision(input: KnowledgeRevisionRestoreInput): Promise<KnowledgeRevisionRestoreResult>;
+    /**
+     * Per-identity read stats for a page (t-677), newest-touched first. This
+     * is the fine-grained "who's reading this" breakdown; it is NOT consulted
+     * by knowledge_maintain's cold/expansion ranking, which deliberately keeps
+     * using the shared pages.hit_count / last_accessed aggregate — that
+     * aggregate already answers "has anyone read this recently" correctly
+     * across readers, so splitting it per-identity there would only make the
+     * cold list miss pages a *different* reader keeps alive.
+     */
+    getAccessStats(pageId: number): Promise<KnowledgeAccessStat[]>;
     /** Close the underlying SQLite connection. */
     close(): void;
 }

package/dist/categories.d.ts

@@ -12,5 +12,7 @@ export declare const MEMORY_CATEGORIES: readonly ['user', 'project', 'self', 'fe
 export declare const EPISODE_CATEGORY = "episode";
 /** Episodes expire by default — they are a tape, not the stack. */
 export declare const EPISODE_DEFAULT_TTL = "48h";
+/** The category that carries evidence-backed confidence (t-338). */
+export declare const FEEDBACK_CATEGORY = "feedback";
 export type MemoryCategory = (typeof MEMORY_CATEGORIES)[number];
 export declare function isMemoryCategory(value: string): value is MemoryCategory;

package/dist/categories.js

@@ -24,6 +24,8 @@ export const MEMORY_CATEGORIES = [
 export const EPISODE_CATEGORY = 'episode';
 /** Episodes expire by default — they are a tape, not the stack. */
 export const EPISODE_DEFAULT_TTL = '48h';
+/** The category that carries evidence-backed confidence (t-338). */
+export const FEEDBACK_CATEGORY = 'feedback';
 export function isMemoryCategory(value) {
     return MEMORY_CATEGORIES.includes(value);
 }

package/dist/cli/args.d.ts

@@ -9,11 +9,26 @@ export interface RawGlobalFlags {
     client?: string;
     model?: string;
     json?: boolean;
+    /** Remote loom-http to run against instead of a local stack (src/cli/remote.ts). */
+    url?: string;
 }
 export declare function resolveEnv(flags: RawGlobalFlags, processEnv: NodeJS.ProcessEnv): ResolvedEnv;
+/**
+ * Index of the first token in `argv` that is neither a leading global flag
+ * nor a global flag's value — i.e. where the subcommand is, if there is
+ * one. Returns `argv.length` when argv holds nothing but globals.
+ *
+ * The help text calls --context-dir/--client/--model/--json GLOBAL, which
+ * has to mean they are accepted before the subcommand as well as after.
+ * Both entry points resolve the subcommand through this so that promise
+ * holds: src/index.ts to decide CLI-vs-MCP, runCli to dispatch. Scanning
+ * only over *leading* globals (rather than searching all of argv for a
+ * known verb) is what keeps a flag's value from being mistaken for one.
+ */
+export declare function firstNonGlobalIndex(argv: string[]): number;
 /**
  * Extracts global flags from an argv slice, returning the remaining argv.
- * Recognizes: --context-dir, --client, --model, --json.
+ * Recognizes: --context-dir, --client, --model, --url, --json — in any position.
  */
 export declare function extractGlobalFlags(argv: string[]): {
     flags: RawGlobalFlags;

package/dist/cli/args.js

@@ -16,9 +16,49 @@ export function resolveEnv(flags, processEnv) {
         json: Boolean(flags.json),
     };
 }
+/**
+ * Global flags that consume the NEXT argv token as their value. Shared by
+ * `extractGlobalFlags` and `firstNonGlobalIndex` so the two cannot drift:
+ * a flag that takes a value must be skipped in pairs when we are looking
+ * past the globals for a subcommand, or `--context-dir recall` reads as an
+ * invocation of `recall`.
+ */
+const VALUED_GLOBAL_FLAGS = new Set([
+    '--context-dir', '--client', '--model', '--url',
+]);
+/** Global flags that stand alone. */
+const BARE_GLOBAL_FLAGS = new Set(['--json']);
+/**
+ * Index of the first token in `argv` that is neither a leading global flag
+ * nor a global flag's value — i.e. where the subcommand is, if there is
+ * one. Returns `argv.length` when argv holds nothing but globals.
+ *
+ * The help text calls --context-dir/--client/--model/--json GLOBAL, which
+ * has to mean they are accepted before the subcommand as well as after.
+ * Both entry points resolve the subcommand through this so that promise
+ * holds: src/index.ts to decide CLI-vs-MCP, runCli to dispatch. Scanning
+ * only over *leading* globals (rather than searching all of argv for a
+ * known verb) is what keeps a flag's value from being mistaken for one.
+ */
+export function firstNonGlobalIndex(argv) {
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i];
+        if (VALUED_GLOBAL_FLAGS.has(a)) {
+            i += 2;
+            continue;
+        }
+        if (BARE_GLOBAL_FLAGS.has(a)) {
+            i += 1;
+            continue;
+        }
+        return i;
+    }
+    return argv.length;
+}
 /**
  * Extracts global flags from an argv slice, returning the remaining argv.
- * Recognizes: --context-dir, --client, --model, --json.
+ * Recognizes: --context-dir, --client, --model, --url, --json — in any position.
  */
 export function extractGlobalFlags(argv) {
     const flags = {};
@@ -37,6 +77,10 @@ export function extractGlobalFlags(argv) {
             flags.model = argv[++i];
             continue;
         }
+        if (a === '--url') {
+            flags.url = argv[++i];
+            continue;
+        }
         if (a === '--json') {
             flags.json = true;
             continue;

package/dist/cli/index.d.ts

@@ -1,2 +1,9 @@
 import type { IOStreams } from './io.js';
 export declare function runCli(argv: string[], io?: IOStreams): Promise<number>;
+/**
+ * The CLI with no remote mode on its path at all: what POST /cli runs
+ * (transport/cli-endpoint.ts). A request arriving over HTTP must never be
+ * able to send the server on to another URL, and that holds by structure
+ * here, not only because the endpoint refuses --url.
+ */
+export declare function runCliLocal(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/index.js

@@ -7,6 +7,9 @@ import { join } from 'node:path';
 import { resolveRepoRoot } from '../config.js';
 import { realStreams } from './io.js';
 import { SUBCOMMANDS } from './subcommands.js';
+import { extractGlobalFlags, firstNonGlobalIndex } from './args.js';
+import { REMOTE_VERBS, runRemote } from './remote.js';
+import { findPiece, isPieceName, runPiece } from './pieces.js';
 const TOP_HELP = `Usage: loom <command> [options]
 
 Commands:
@@ -19,6 +22,7 @@ Commands:
                      Browse / clean / find duplicates / health report
   knowledge write|recall|maintain
                      Write / search / health-report the knowledge store
+  person show|list   Read person cards (condensed current state per person)
   update-identity    Edit preferences.md / self-model.md sections
   bootstrap          Initialize a fresh agent
   serve              Explicit MCP stdio startup (same as no args)
@@ -27,11 +31,19 @@ Commands:
   install           Write loom-setup skill into a harness's skills dir
   doctor            Probe the loom environment (read-only)
   migrate           Apply pending schema migrations to memories.db
+  pieces            List installed pieces (loom-<name> on PATH)
+
+Pieces: \`loom <name> ...\` runs an installed extension, loom-<name> on PATH
+(e.g. loom tasks list). Core commands always win. See docs/extensions.md.
 
 Global flags:
   --context-dir <path>   Agent context dir (default: $LOOM_CONTEXT_DIR or ~/.config/loom/default)
   --client <name>        Harness adapter hint (default: $LOOM_CLIENT)
   --model <name>         Model manifest hint (default: $LOOM_MODEL)
+  --url <url>            Run against a loom-http server (default: $LOOM_URL), e.g.
+                         http://host:8787/mcp. Bearer token from $LOOM_TOKEN_FILE.
+                         Applies to wake, recall, remember, update, forget,
+                         memory, knowledge, person; other commands stay local.
   --json                 Machine-readable output
   --help, -h             Show help
   --version, -V          Print loom version
@@ -43,7 +55,60 @@ async function readVersion() {
     return pkg.version;
 }
 export async function runCli(argv, io = realStreams()) {
-    const first = argv[0];
+    // A piece (docs/extensions.md): not a core command, and loom-<name> is on PATH.
+    const pieceIdx = firstNonGlobalIndex(argv);
+    const pieceName = argv[pieceIdx];
+    if (isPieceName(pieceName)) {
+        const path = findPiece(pieceName, io.env);
+        if (path) {
+            if (pieceIdx > 0) {
+                io.stderr(`loom: global flags (${argv.slice(0, pieceIdx).join(' ')}) don't apply to pieces; put the piece's own flags after its name.\n`);
+                return 2;
+            }
+            return runPiece(path, argv.slice(pieceIdx + 1), io);
+        }
+    }
+    const resolved = await resolveSubcommand(argv, io);
+    if (typeof resolved === 'number')
+        return resolved;
+    const { sub, rest } = resolved;
+    // Remote mode: the store verbs go to loom-http when a URL is set.
+    const url = extractGlobalFlags(rest).flags.url;
+    if (rest.includes('--url') && !url) {
+        io.stderr(`--url needs a value (a loom-http URL, e.g. http://host:8787/mcp).\n`);
+        return 2;
+    }
+    if (REMOTE_VERBS.has(sub)) {
+        const target = url ?? io.env.LOOM_URL;
+        if (target)
+            return runRemote(sub, rest, target, io);
+    }
+    else if (url !== undefined) {
+        io.stderr(`--url only applies to ${[...REMOTE_VERBS].join(', ')}; ${sub} runs locally.\n`);
+        return 2;
+    }
+    return dispatch(sub, rest, io);
+}
+/**
+ * The CLI with no remote mode on its path at all: what POST /cli runs
+ * (transport/cli-endpoint.ts). A request arriving over HTTP must never be
+ * able to send the server on to another URL, and that holds by structure
+ * here, not only because the endpoint refuses --url.
+ */
+export async function runCliLocal(argv, io) {
+    const resolved = await resolveSubcommand(argv, io);
+    if (typeof resolved === 'number')
+        return resolved;
+    return dispatch(resolved.sub, resolved.rest, io);
+}
+/** The subcommand and the argv it gets, or the exit code when there's nothing to dispatch. */
+async function resolveSubcommand(argv, io) {
+    // The subcommand is the first token that is not a leading global flag,
+    // so the flags the help text calls global work in front of it too. When
+    // it is already at argv[0] — the overwhelmingly common form — subIdx is
+    // 0 and every line below behaves exactly as it did before.
+    const subIdx = firstNonGlobalIndex(argv);
+    const first = argv[subIdx];
     if (first === '--help' || first === '-h' || first === undefined) {
         io.stdout(TOP_HELP);
         return 0;
@@ -54,11 +119,16 @@ export async function runCli(argv, io = realStreams()) {
     }
     if (!SUBCOMMANDS.includes(first)) {
         io.stderr(`Unknown subcommand: ${first}\n`);
+        if (isPieceName(first))
+            io.stderr(`(no piece installed either: nothing named loom-${first} on PATH; \`loom pieces\` lists what is)\n`);
         io.stderr(TOP_HELP);
         return 2;
     }
-    const sub = first;
-    const rest = argv.slice(1);
+    // Drop only the subcommand token; the globals that preceded it stay in
+    // argv so each command's own extractGlobalFlags still sees them.
+    return { sub: first, rest: [...argv.slice(0, subIdx), ...argv.slice(subIdx + 1)] };
+}
+async function dispatch(sub, rest, io) {
     switch (sub) {
         case 'wake': {
             const { run } = await import('./wake.js');
@@ -76,6 +146,10 @@ export async function runCli(argv, io = realStreams()) {
             const { run } = await import('./knowledge.js');
             return run(rest, io);
         }
+        case 'person': {
+            const { run } = await import('./person.js');
+            return run(rest, io);
+        }
         case 'forget': {
             const { run } = await import('./forget.js');
             return run(rest, io);
@@ -120,6 +194,10 @@ export async function runCli(argv, io = realStreams()) {
             const { run } = await import('./migrate.js');
             return run(rest, io);
         }
+        case 'pieces': {
+            const { runPiecesCommand } = await import('./pieces.js');
+            return runPiecesCommand(rest, io);
+        }
         default:
             io.stderr(`Subcommand not implemented yet: ${sub}\n`);
             return 2;

package/dist/cli/knowledge.js

@@ -6,6 +6,7 @@ import { knowledgeWrite } from '../tools/knowledge-write.js';
 import { knowledgeRecall } from '../tools/knowledge-recall.js';
 import { knowledgeMaintain } from '../tools/knowledge-maintain.js';
 import { createKnowledgeBackend } from '../backends/index.js';
+import { resolveIdentityName } from '../config.js';
 import { extractGlobalFlags, resolveEnv } from './args.js';
 import { renderJson } from './io.js';
 const USAGE = `Usage: loom knowledge <subcommand> [options]
@@ -13,7 +14,7 @@ const USAGE = `Usage: loom knowledge <subcommand> [options]
 Subcommands:
   write     Upsert an entity page (create or append/revise body in place)
   recall    Search knowledge pages (LIKE over title+body+domain)
-  maintain  Read-only health report (expansion candidates, cold pages, misfile audit)
+  maintain  Read-only health report (expansion candidates, cold pages, misfile audit, person-page check)
 
 Options (write):
   --slug <slug>              Entity key for upsert (default: derived from title)
@@ -112,6 +113,7 @@ export async function run(argv, io) {
                     body,
                     sourcing,
                     citations,
+                    actor: resolveIdentityName(env.contextDir),
                 });
                 renderJson(io, result);
                 return 0;
@@ -210,6 +212,7 @@ export async function run(argv, io) {
         expansionHitThreshold,
         thinBodyThreshold,
         coldDays,
+        personCards: true,
     });
     io.stdout(text.endsWith('\n') ? text : text + '\n');
     return 0;

package/dist/cli/memory.js

@@ -20,7 +20,7 @@ const USAGE = `Usage: loom memory <subcommand> [options]
 
 Subcommands:
   list      Browse memories (table or --json)
-  prune     Report / remove expired and stale memories
+  prune     Report / archive expired memories; report stale ones
   similar   Surface memories semantically near a ref or text
   audit     One-shot health report (counts, stale, duplicates, expired)
   archive   Soft-retire a memory with a tombstone (recoverable)
@@ -42,7 +42,7 @@ Options (list):
 
 Options (prune):
   --stale-days <n>     Stale threshold in days
-  --dry-run            Report what would be pruned, don't delete
+  --dry-run            Report what would be archived, don't archive
   --json               Emit PruneResult
 
 Options (similar):

package/dist/cli/person.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;