quilltap 4.6.0-dev → 4.6.0-dev.39

package/lib/completion/zsh.template

@@ -16,6 +16,7 @@ _quilltap() {
     '(-v --version)'{-v,--version}'[Show version number]'
     '(-h --help)'{-h,--help}'[Show help message]'
     '--update[Force re-download of application files]'
+    '--passphrase[Database passphrase]:passphrase:'
   )
 
   subcommands=(
@@ -25,6 +26,8 @@ _quilltap() {
     'instances:Register or inspect named Quilltap instances'
     'memories:Search, browse, and graph memories'
     'memory-diff:Dump existing memories and dry-run re-extraction'
+    'logs:Tail or print an instance log file'
+    'migrations:Inspect migration status'
     'completion:Generate shell completion scripts'
   )
 
@@ -67,6 +70,12 @@ _quilltap_subcommand() {
     memory-diff)
       _quilltap_memory_diff
       ;;
+    logs)
+      _quilltap_logs
+      ;;
+    migrations)
+      _quilltap_migrations
+      ;;
     completion)
       _quilltap_completion
       ;;
@@ -74,7 +83,7 @@ _quilltap_subcommand() {
 }
 
 _quilltap_db() {
-  local -a subverbs
+  local -a subverbs db_opts
   subverbs=(
     'schema:Show database schema'
     'find:Find entities by name'
@@ -89,11 +98,46 @@ _quilltap_db() {
     'integrity:Check database integrity'
   )
 
-  _values 'db subcommand' $subverbs
+  db_opts=(
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '--passphrase[Database passphrase]:passphrase:'
+    '--json[JSON output]'
+    '--limit[Result limit]:limit:'
+    '--grep[Substring search]:text:'
+    '--character[Character name or id]:character:'
+    '--project[Project name or id]:project:'
+    '--about[Subject character]:character:'
+    '--source[Memory source]:source:(AUTO MANUAL)'
+    '--chat[Chat name or id]:chat:'
+    '--message[Message id]:id:'
+    '--rendered[Render rich content]'
+    '--field[Log field]:field:(request response both)'
+    '--tail[Tail N rows]:n:'
+    '--last[Last N items]:n:'
+    '--full[Full output]'
+    '--from[Participant filter]:participant:'
+    '--type[Filter by type]:type:'
+    '--out[Output directory]:path:_files -/'
+    '--tables[List tables (low-level)]'
+    '--count[Count rows in table]:table:'
+    '--repl[Open SQL REPL]'
+    '--llm-logs[Target llm-logs database]'
+    '--mount-points[Target mount-index database]'
+    '--lock-status[Show instance lock status]'
+    '--lock-clean[Clean stale lock]'
+    '--lock-override[Override active lock]'
+    '(-h --help)'{-h,--help}'[Show help]'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'db subcommand' subverbs
+  fi
+  _arguments $db_opts
 }
 
 _quilltap_docs() {
-  local -a subverbs
+  local -a subverbs docs_opts
   subverbs=(
     'list:List all mount points'
     'show:Details for one mount point'
@@ -115,11 +159,45 @@ _quilltap_docs() {
     'copy:Copy file'
   )
 
-  _values 'docs subcommand' $subverbs
+  docs_opts=(
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '--passphrase[Database passphrase]:passphrase:'
+    '(-p --port)'{-p,--port}'[Server port]:port:'
+    '--json[JSON output]'
+    '--mount[Mount name or id]:mount:'
+    '--folder[Folder filter]:folder:'
+    '--force[Force operation]'
+    '--rendered[Render rich content]'
+    '--links[Include link details]'
+    '--type[Filter by type]:type:(file folder)'
+    '--ext[Extension filter]:ext:'
+    '--limit[Result limit]:n:'
+    '--max[Maximum results]:n:'
+    '--context[Context lines]:n:'
+    '--top[Top N results]:n:'
+    '--threshold[Similarity threshold]:value:'
+    '--ignore-case[Case-insensitive search]'
+    '-l[Paths only]'
+    '--wait[Wait for completion]'
+    '(-R --recursive)'{-R,--recursive}'[Recursive listing]'
+    '--sort[Sort field]:field:(name path size modified created)'
+    '(-r --reverse)'{-r,--reverse}'[Reverse sort order]'
+    '--depth[Maximum traversal depth]:n:'
+    '--max-nodes[Maximum nodes in graph]:n:'
+    '--long[Long-form output]'
+    '--semantic[Use semantic search]'
+    '(-h --help)'{-h,--help}'[Show help]'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'docs subcommand' subverbs
+  fi
+  _arguments $docs_opts
 }
 
 _quilltap_themes() {
-  local -a subverbs
+  local -a subverbs registry_verbs themes_opts registry_opts
   subverbs=(
     'list:List available themes'
     'install:Install a theme'
@@ -132,17 +210,50 @@ _quilltap_themes() {
     'registry:Manage registries'
   )
 
-  _values 'themes subcommand' $subverbs
+  themes_opts=(
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '(-o --output)'{-o,--output}'[Output path]:path:_files'
+    '(-h --help)'{-h,--help}'[Show help]'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'themes subcommand' subverbs
+    return
+  fi
+
+  if [[ "$words[2]" == "registry" ]]; then
+    registry_verbs=(
+      'list:List registries'
+      'add:Add a registry'
+      'remove:Remove a registry'
+      'refresh:Refresh registries'
+      'keygen:Generate Ed25519 key'
+      'sign:Sign a registry or bundle'
+    )
+    registry_opts=(
+      '(-k --key)'{-k,--key}'[Signing key path]:path:_files'
+      '(-n --name)'{-n,--name}'[Registry name]:name:'
+      '(-o --output)'{-o,--output}'[Output path]:path:_files'
+    )
+    if (( CURRENT == 3 )); then
+      _describe 'registry subcommand' registry_verbs
+    fi
+    _arguments $registry_opts
+    return
+  fi
+
+  _arguments $themes_opts
 }
 
 _quilltap_instances() {
-  local -a subverbs
+  local -a subverbs inst_opts
   subverbs=(
     'list:List registered instances'
-    'ls:List instances'
+    'ls:List registered instances'
     'show:Show instance details'
-    'path:Show instance path'
-    'where:Show instance path'
+    'path:Show instances.json path'
+    'where:Show instances.json path'
     'add:Register a new instance'
     'create:Register a new instance'
     'remove:Unregister an instance'
@@ -150,9 +261,32 @@ _quilltap_instances() {
     'delete:Unregister an instance'
     'set-passphrase:Set instance passphrase'
     'passphrase:Set instance passphrase'
+    'default:Set/show/clear the default instance'
+    'rename:Rename an instance (preserves passphrase)'
+  )
+
+  inst_opts=(
+    '--names-only[Print one name per line (for completion)]'
+    '--json[JSON output]'
+    '--clear[Clear value (for default)]'
+    '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  _values 'instances subcommand' $subverbs
+  if (( CURRENT == 2 )); then
+    _describe 'instances subcommand' subverbs
+    return
+  fi
+
+  case "$words[2]" in
+    show|remove|rm|delete|set-passphrase|passphrase|default|rename)
+      if (( CURRENT == 3 )); then
+        _values 'instance' ${(f)"$(command quilltap instances list --names-only 2>/dev/null)"}
+        return
+      fi
+      ;;
+  esac
+
+  _arguments $inst_opts
 }
 
 _quilltap_memories() {
@@ -168,24 +302,44 @@ _quilltap_memories() {
   )
 
   mem_opts=(
-    '--character[Character name or id]'
-    '--about[Subject of memory]'
-    '--source[AUTO or MANUAL]'
-    '--chat[Chat id or title]'
-    '--project[Project name or id]'
-    '--since[Since timestamp]'
-    '--until[Until timestamp]'
-    '--min-importance[Minimum importance]'
-    '--min-reinforced[Minimum reinforcement]'
-    '--has-embedding[Has embedding]'
-    '--no-embedding[No embedding]'
-    '--sort[Sort field]'
-    '--limit[Result limit]'
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '--passphrase[Database passphrase]:passphrase:'
+    '(-p --port)'{-p,--port}'[Server port]:port:'
     '--json[JSON output]'
-    '--help[Show help]'
+    '--character[Character name or id]:character:'
+    '--about[Subject of memory]:character:'
+    '--source[Memory source]:source:(AUTO MANUAL)'
+    '--chat[Chat id or title]:chat:'
+    '--project[Project name or id]:project:'
+    '--since[Since timestamp]:date:'
+    '--until[Until timestamp]:date:'
+    '--min-importance[Minimum importance]:value:'
+    '--min-reinforced[Minimum reinforcement]:value:'
+    '--has-embedding[Only memories with embeddings]'
+    '--no-embedding[Only memories without embeddings]'
+    '--sort[Sort field]:field:(reinforced importance created accessed reinforcement-count links)'
+    '(-r --reverse)'{-r,--reverse}'[Reverse sort]'
+    '--limit[Result limit]:n:'
+    '--full-titles[Show full titles]'
+    '--in[Restrict find-in field]:field:'
+    '--no-related[Hide related neighbors]'
+    '--list[List-only output]'
+    '(-i --ignore-case)'{-i,--ignore-case}'[Case-insensitive]'
+    '(-l --paths-only)'{-l,--paths-only}'[Paths only]'
+    '--max[Maximum results]:n:'
+    '--context[Context lines]:n:'
+    '--depth[Walk depth]:n:'
+    '--max-nodes[Maximum nodes]:n:'
+    '--semantic[Semantic search]'
+    '--top[Top N results]:n:'
+    '--threshold[Similarity threshold]:value:'
+    '(-h --help)'{-h,--help}'[Show help]'
   )
 
-  _values 'memories subcommand' $subverbs
+  if (( CURRENT == 2 )); then
+    _describe 'memories subcommand' subverbs
+  fi
   _arguments $mem_opts
 }
 
@@ -193,7 +347,46 @@ _quilltap_memory_diff() {
   _arguments \
     '(-h --help)'{-h,--help}'[Show help]' \
     '(-i --instance)'{-i,--instance}'[Use instance]:instance:_quilltap_instance_names' \
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories' \
+    '--passphrase[Database passphrase]:passphrase:' \
+    '(-p --port)'{-p,--port}'[Server port]:port:' \
+    '--concurrency[Concurrency limit]:n:' \
+    '--out[Output file]:path:_files'
+}
+
+_quilltap_logs() {
+  _arguments \
+    '(-h --help)'{-h,--help}'[Show help]' \
+    '(-i --instance)'{-i,--instance}'[Use instance]:instance:_quilltap_instance_names' \
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories' \
+    '--passphrase[Database passphrase]:passphrase:' \
+    '--stream[Which log stream]:stream:(combined error stdout stderr startup)' \
+    '--tail[Last N lines (0=full)]:n:' \
+    '(-f --follow)'{-f,--follow}'[Stream new lines]' \
+    '--grep[Regex filter]:pattern:'
+}
+
+_quilltap_migrations() {
+  local -a subverbs mig_opts
+  subverbs=(
+    'status:Migration status'
+    'pending:List pending migrations'
+    'run:Run pending migrations (use --dry-run)'
+  )
+
+  mig_opts=(
+    '(-i --instance)'{-i,--instance}'[Registered instance name]:instance:_quilltap_instance_names'
     '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
+    '--passphrase[Database passphrase]:passphrase:'
+    '--dry-run[Dry run]'
+    '--json[JSON output]'
+    '(-h --help)'{-h,--help}'[Show help]'
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'migrations subcommand' subverbs
+  fi
+  _arguments $mig_opts
 }
 
 _quilltap_completion() {

package/lib/db-commands.js

@@ -561,6 +561,12 @@ function cmdLog(args, ctx) {
     if (!row) throw new Error(`No llm_log with id ${id}`);
     if (json) return printJson(row);
 
+    let finishReason = null;
+    try {
+      const parsed = typeof row.response === 'string' ? JSON.parse(row.response) : row.response;
+      if (parsed && typeof parsed.finishReason === 'string') finishReason = parsed.finishReason;
+    } catch { /* leave null */ }
+
     printRecord(`LLM log ${row.id}`, {
       createdAt: row.createdAt,
       type: row.type,
@@ -570,6 +576,7 @@ function cmdLog(args, ctx) {
       messageId: row.messageId,
       characterId: row.characterId,
       durationMs: row.durationMs,
+      finishReason,
       usage: row.usage,
       cacheUsage: row.cacheUsage,
     });
@@ -636,6 +643,323 @@ function cmdMemories(args, ctx) {
   }
 }
 
+// ---------- verb: characters ----------
+
+// Vault files that the character-properties overlay manages today. Must stay
+// in sync with `CHARACTER_VAULT_DESCRIPTORS` in
+// lib/database/repositories/character-properties-overlay.ts. When the 4.6
+// vault-cutover migration lands, every character is expected to have all of
+// these present.
+const EXPECTED_VAULT_SINGLE_FILES = [
+  'properties.json',
+  'identity.md',
+  'description.md',
+  'manifesto.md',
+  'personality.md',
+  'example-dialogues.md',
+  'physical-description.md',
+  'physical-prompts.json',
+];
+
+function safeJsonArray(raw) {
+  if (raw == null || raw === '') return [];
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}
+
+function normalizeEmpty(v) {
+  if (v == null) return '';
+  return v;
+}
+
+function inspectCharacterVault(row, mounts) {
+  // `flag` / `*Db` / divergence reporting only make sense before the 4.6
+  // vault cutover, when the DB still carried the content columns. After
+  // the cutover the columns are gone and the vault is the only source of
+  // truth — `row` won't carry them. Treat them as null and skip the
+  // divergence check; the file-presence count is still useful.
+  const preCutover = row.identity !== undefined
+    || row.description !== undefined
+    || row.systemPrompts !== undefined;
+
+  const status = {
+    id: row.id,
+    name: row.name,
+    flag: row.readPropertiesFromDocumentStore == null
+      ? null
+      : Number(row.readPropertiesFromDocumentStore),
+    mountPointId: row.characterDocumentMountPointId || null,
+    vault: 'missing',
+    presentSingleFiles: 0,
+    expectedSingleFiles: EXPECTED_VAULT_SINGLE_FILES.length,
+    missingSingleFiles: [],
+    promptsVault: 0,
+    promptsDb: 0,
+    scenariosVault: 0,
+    scenariosDb: 0,
+    wardrobeVault: 0,
+    diverged: [],
+    issue: null,
+    preCutover,
+  };
+
+  if (preCutover) {
+    status.promptsDb = safeJsonArray(row.systemPrompts).length;
+    status.scenariosDb = safeJsonArray(row.scenarios).length;
+  }
+
+  if (!row.characterDocumentMountPointId) {
+    status.issue = 'no vault';
+    return status;
+  }
+
+  status.vault = 'present';
+  const mountPointId = row.characterDocumentMountPointId;
+
+  // One-shot listing of every link for this vault; the rest is just lookups.
+  const links = mounts.prepare(
+    'SELECT relativePath, fileId FROM doc_mount_file_links WHERE mountPointId = ?'
+  ).all(mountPointId);
+  const byPath = new Map();
+  for (const link of links) {
+    byPath.set(link.relativePath.toLowerCase(), link);
+  }
+
+  for (const p of EXPECTED_VAULT_SINGLE_FILES) {
+    if (byPath.has(p)) {
+      status.presentSingleFiles++;
+    } else {
+      status.missingSingleFiles.push(p);
+    }
+  }
+
+  for (const [p] of byPath) {
+    if (p.startsWith('prompts/') && p.endsWith('.md')) status.promptsVault++;
+    else if (p.startsWith('scenarios/') && p.endsWith('.md')) status.scenariosVault++;
+    else if (p.startsWith('wardrobe/') && p.endsWith('.md')) status.wardrobeVault++;
+  }
+
+  // Compare vault contents to DB row for each managed field where the
+  // corresponding file is actually present. Only meaningful pre-cutover;
+  // post-cutover the DB no longer carries the columns to compare against.
+  if (preCutover) {
+    const docStmt = mounts.prepare(
+      'SELECT content FROM doc_mount_documents WHERE fileId = ?'
+    );
+    const readVault = (relPath) => {
+      const link = byPath.get(relPath);
+      if (!link) return null;
+      const doc = docStmt.get(link.fileId);
+      return doc ? doc.content : null;
+    };
+
+    const mdFields = [
+      ['identity.md', 'identity'],
+      ['description.md', 'description'],
+      ['manifesto.md', 'manifesto'],
+      ['personality.md', 'personality'],
+      ['example-dialogues.md', 'exampleDialogues'],
+    ];
+    for (const [vaultPath, dbField] of mdFields) {
+      const vault = readVault(vaultPath);
+      if (vault === null) continue;
+      const db = row[dbField] ?? '';
+      if (vault !== db) status.diverged.push(dbField);
+    }
+
+    const propsRaw = readVault('properties.json');
+    if (propsRaw !== null) {
+      try {
+        const props = JSON.parse(propsRaw);
+        const scalarChecks = [
+          ['pronouns', row.pronouns],
+          ['title', row.title],
+          ['firstMessage', row.firstMessage],
+          ['talkativeness', row.talkativeness],
+        ];
+        for (const [k, dbVal] of scalarChecks) {
+          if (normalizeEmpty(props[k]) !== normalizeEmpty(dbVal)) {
+            status.diverged.push(k);
+          }
+        }
+        const vaultAliases = JSON.stringify(Array.isArray(props.aliases) ? props.aliases : []);
+        const dbAliases = JSON.stringify(safeJsonArray(row.aliases));
+        if (vaultAliases !== dbAliases) status.diverged.push('aliases');
+        // systemTransparency: tristate (0 / 1 / null), only reported if vault has it
+        if (props.systemTransparency !== undefined) {
+          if ((props.systemTransparency ?? null) !== (row.systemTransparency ?? null)) {
+            status.diverged.push('systemTransparency');
+          }
+        }
+      } catch {
+        status.diverged.push('properties.json:unparseable');
+      }
+    }
+
+    const physArr = safeJsonArray(row.physicalDescriptions);
+    const primary = physArr[0] || null;
+    const physMd = readVault('physical-description.md');
+    if (physMd !== null) {
+      const dbVal = primary && primary.fullDescription != null ? primary.fullDescription : '';
+      if (physMd !== dbVal) status.diverged.push('physicalDescription.fullDescription');
+    }
+    const physJsonRaw = readVault('physical-prompts.json');
+    if (physJsonRaw !== null) {
+      try {
+        const physJson = JSON.parse(physJsonRaw);
+        const promptChecks = [
+          ['short', primary?.shortPrompt],
+          ['medium', primary?.mediumPrompt],
+          ['long', primary?.longPrompt],
+          ['complete', primary?.completePrompt],
+        ];
+        for (const [k, dbVal] of promptChecks) {
+          if (normalizeEmpty(physJson[k]) !== normalizeEmpty(dbVal)) {
+            status.diverged.push(`physical.${k}Prompt`);
+          }
+        }
+      } catch {
+        status.diverged.push('physical-prompts.json:unparseable');
+      }
+    }
+
+    if (status.promptsVault !== status.promptsDb) {
+      status.diverged.push(`systemPrompts:count(vault=${status.promptsVault},db=${status.promptsDb})`);
+    }
+    if (status.scenariosVault !== status.scenariosDb) {
+      status.diverged.push(`scenarios:count(vault=${status.scenariosVault},db=${status.scenariosDb})`);
+    }
+  }
+
+  if (status.missingSingleFiles.length === EXPECTED_VAULT_SINGLE_FILES.length) {
+    status.issue = 'vault empty';
+  } else if (status.missingSingleFiles.length > 0) {
+    status.issue = `${status.missingSingleFiles.length} files missing`;
+  } else if (status.diverged.length > 0) {
+    status.issue = `diverged (${status.diverged.length})`;
+  } else if (!preCutover) {
+    status.issue = 'ok (post-cutover, vault is canonical)';
+  } else if (status.flag === 1) {
+    status.issue = 'ok (vault authoritative)';
+  } else {
+    status.issue = 'ok (db matches vault)';
+  }
+  return status;
+}
+
+function cmdCharacters(args, ctx) {
+  const { flags, positional } = parseSubArgs(args);
+  const sub = positional[0] || 'status';
+  if (sub !== 'status') {
+    throw new Error(`Unknown characters subcommand: ${sub}. Try: status`);
+  }
+
+  const json = asBool(flags.json);
+  const limit = asInt(flags.limit, 0);
+  const onlyDiverged = asBool(flags.diverged);
+  const onlyBlocked = asBool(flags.blocked);
+  const idQuery = flags.id ? String(flags.id) : null;
+
+  const main = ctx.openMain();
+  const mounts = ctx.openMounts();
+  try {
+    // Probe the schema so this verb works both pre- and post-cutover: after
+    // the 4.6 migration the content columns are gone, so we can only ask
+    // for what's there.
+    const existing = new Set(
+      main.prepare('PRAGMA table_info(characters)')
+        .all()
+        .map(r => r.name)
+    );
+    const wanted = [
+      'id', 'name', 'characterDocumentMountPointId', 'systemTransparency',
+      'readPropertiesFromDocumentStore',
+      'identity', 'description', 'manifesto', 'personality', 'exampleDialogues',
+      'pronouns', 'aliases', 'title', 'firstMessage', 'talkativeness',
+      'physicalDescriptions', 'systemPrompts', 'scenarios',
+    ];
+    const cols = wanted.filter(c => existing.has(c));
+    let sql = `SELECT ${cols.join(', ')} FROM characters`;
+    const params = [];
+    if (idQuery) {
+      const c = resolveCharacter(main, idQuery);
+      sql += ' WHERE id = ?';
+      params.push(c.id);
+    } else {
+      sql += ' ORDER BY name';
+      if (limit > 0) {
+        sql += ' LIMIT ?';
+        params.push(limit);
+      }
+    }
+    const rows = main.prepare(sql).all(...params);
+
+    const all = rows.map(r => inspectCharacterVault(r, mounts));
+    const filtered = all.filter(s => {
+      if (onlyBlocked && !(s.issue && (s.issue === 'no vault' || s.issue === 'vault empty' || s.issue.endsWith(' files missing')))) {
+        return false;
+      }
+      if (onlyDiverged && s.diverged.length === 0 && (!s.missingSingleFiles || s.missingSingleFiles.length === 0)) {
+        return false;
+      }
+      return true;
+    });
+
+    if (json) {
+      const summary = {
+        totalScanned: all.length,
+        returned: filtered.length,
+        counts: summarizeCharacterStatuses(all),
+        characters: filtered,
+      };
+      return printJson(summary);
+    }
+
+    const summary = summarizeCharacterStatuses(all);
+    const headline = `Scanned ${all.length} character${all.length === 1 ? '' : 's'}: ` +
+      `${summary.ok} ok, ${summary.diverged} diverged, ${summary.missingFiles} with missing files, ` +
+      `${summary.noVault} with no vault, ${summary.empty} empty.`;
+    console.log(headline);
+    console.log('');
+    printTable(filtered.map(s => ({
+      id: s.id.slice(0, 8),
+      name: truncate(s.name, 28),
+      flag: s.flag == null ? '-' : s.flag,
+      vault: s.vault,
+      files: s.vault === 'missing' ? '-' : `${s.presentSingleFiles}/${s.expectedSingleFiles}`,
+      prompts: s.vault === 'missing' ? '-' : `${s.promptsVault}/${s.promptsDb}`,
+      scenarios: s.vault === 'missing' ? '-' : `${s.scenariosVault}/${s.scenariosDb}`,
+      wardrobe: s.vault === 'missing' ? '-' : s.wardrobeVault,
+      status: truncate(s.issue, 60),
+    })));
+
+    if (filtered.length > 0 && filtered.some(s => s.diverged.length > 0)) {
+      console.log('');
+      console.log('Run with --json to see the full diverged-field list per character.');
+    }
+  } finally {
+    try { mounts.close(); } catch {}
+    try { main.close(); } catch {}
+  }
+}
+
+function summarizeCharacterStatuses(all) {
+  let ok = 0, diverged = 0, missingFiles = 0, noVault = 0, empty = 0;
+  for (const s of all) {
+    if (!s.issue) continue;
+    if (s.issue.startsWith('ok')) ok++;
+    else if (s.issue === 'no vault') noVault++;
+    else if (s.issue === 'vault empty') empty++;
+    else if (s.issue.endsWith(' files missing')) missingFiles++;
+    else if (s.issue.startsWith('diverged')) diverged++;
+  }
+  return { ok, diverged, missingFiles, noVault, empty };
+}
+
 // ---------- verb: optimize ----------
 
 const OPTIMIZE_TARGETS = {
@@ -1105,6 +1429,7 @@ const VERBS = {
   message: cmdMessage,
   log: cmdLog,
   memories: cmdMemories,
+  characters: cmdCharacters,
   optimize: cmdOptimize,
   backup: cmdBackup,
   integrity: cmdIntegrity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.6.0-dev",
+  "version": "4.6.0-dev.39",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",