quilltap 4.6.0-dev.99 → 4.6.0

package/README.md

@@ -115,6 +115,7 @@ quilltap db logs --tail 20                  # Recent LLM logs
 quilltap db message <id>                    # Full content of one message
 quilltap db log <id> [--field request|response|both]
 quilltap db memories --character Friday [--about Amy] [--source AUTO]
+quilltap db characters status               # Per-character vault readiness (--id, --diverged, --blocked)
 ```
 
 ### Maintenance and Snapshots
@@ -157,6 +158,7 @@ In the REPL, `.cols <table>` and `.find <text>` mirror the subcommand helpers.
 quilltap docs list                              # All mounts
 quilltap docs show <mount>                      # One mount, with counts
 quilltap docs ls <mount> [path] [--links]       # POSIX-flavoured listing (alias: dir)
+quilltap docs tree <mount> [path]               # ASCII tree of a folder hierarchy (--depth, --max-nodes)
 quilltap docs read [--rendered] <mount> <path>  # File contents → stdout
 quilltap docs export <mount> <outputDir>        # Mount → directory
 quilltap docs find <pattern>                    # Substring match on file names (--mount, --ext, --type, --limit)
@@ -286,7 +288,7 @@ Dynamic completions shell out to `quilltap`'s own subcommands. If the active ins
 
 ## Requirements
 
-- Node.js 18 or later
+- Node.js 24 or later
 
 ## Other Ways to Run Quilltap
 

package/bin/quilltap.js

@@ -116,6 +116,8 @@ Examples:
   quilltap -d /mnt/data/quilltap        # Custom data directory
   quilltap -o                           # Start and open browser
   quilltap --update                     # Re-download app files
+  quilltap --instance Friday db schema  # Universal flags (-i/--instance, -d/--data-dir,
+                                        #   --passphrase) work before or after a subcommand
 
 More info: https://quilltap.ai
 `);
@@ -1047,51 +1049,81 @@ async function dbCommand(args) {
   }
 }
 
-// Route to subcommand or main
-if (process.argv[2] === 'db') {
-  dbCommand(process.argv.slice(3));
-} else if (process.argv[2] === 'themes') {
+// Route to subcommand or main.
+//
+// Universal flags (-i/--instance, -d/--data-dir, --passphrase, -p/--port) may
+// appear *before* the subcommand, e.g. `quilltap --instance Friday db schema`.
+// We locate the subcommand by walking the args and skipping those
+// value-taking flags (so an instance literally named "db" is not mistaken for
+// the subcommand), then hand every other arg — including the leading flags —
+// to the subcommand. Each subcommand parses these flags position-independently,
+// so they behave the same before or after the verb.
+const SUBCOMMANDS = new Set([
+  'db', 'themes', 'docs', 'memories', 'instances', 'memory-diff', 'completion', 'logs', 'migrations',
+]);
+// Global flags that consume the following token as their value.
+const GLOBAL_VALUE_FLAGS = new Set(['-p', '--port', '-d', '--data-dir', '-i', '--instance', '--passphrase']);
+
+function locateSubcommand(argv) {
+  for (let k = 0; k < argv.length; k++) {
+    const a = argv[k];
+    if (GLOBAL_VALUE_FLAGS.has(a)) { k++; continue; } // skip the flag's value
+    if (a.startsWith('-')) continue;                  // boolean / unknown flag
+    return SUBCOMMANDS.has(a) ? k : -1;               // first bare token decides
+  }
+  return -1;
+}
+
+const cliArgs = process.argv.slice(2);
+const subIdx = locateSubcommand(cliArgs);
+const subName = subIdx >= 0 ? cliArgs[subIdx] : '';
+// Everything except the subcommand token itself (leading global flags kept).
+const subArgs = subIdx >= 0 ? [...cliArgs.slice(0, subIdx), ...cliArgs.slice(subIdx + 1)] : [];
+
+if (subName === 'db') {
+  dbCommand(subArgs);
+} else if (subName === 'themes') {
   const { themesCommand } = require('../lib/theme-commands');
-  themesCommand(process.argv.slice(3));
-} else if (process.argv[2] === 'docs') {
+  themesCommand(subArgs);
+} else if (subName === 'docs') {
   const { docsCommand } = require('../lib/docs-commands');
-  docsCommand(process.argv.slice(3));
-} else if (process.argv[2] === 'memories') {
+  docsCommand(subArgs);
+} else if (subName === 'memories') {
   const { memoriesCommand } = require('../lib/memories-commands');
-  memoriesCommand(process.argv.slice(3)).catch(err => {
+  memoriesCommand(subArgs).catch(err => {
     if (!err.silent) {
       console.error(`Error: ${err.message}`);
     }
     const code = err.exitCode != null ? err.exitCode : (err.ambiguous ? 2 : 1);
     process.exit(code);
   });
-} else if (process.argv[2] === 'instances') {
+} else if (subName === 'instances') {
   const { instancesCommand } = require('../lib/instances-commands');
-  instancesCommand(process.argv.slice(3)).catch(err => {
+  instancesCommand(subArgs).catch(err => {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
-} else if (process.argv[2] === 'memory-diff') {
+} else if (subName === 'memory-diff') {
   const { memoryDiffCommand } = require('../lib/memory-diff-command');
-  memoryDiffCommand(process.argv.slice(3)).catch(err => {
+  memoryDiffCommand(subArgs).catch(err => {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
-} else if (process.argv[2] === 'completion') {
+} else if (subName === 'completion') {
   const { completionCommand } = require('../lib/completion-commands');
-  completionCommand(process.argv.slice(3)).catch(err => {
+  completionCommand(subArgs).catch(err => {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
-} else if (process.argv[2] === 'logs') {
+} else if (subName === 'logs') {
   const { logsCommand } = require('../lib/logs-commands');
-  logsCommand(process.argv.slice(3)).catch(err => {
+  logsCommand(subArgs).catch(err => {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
-} else if (process.argv[2] === 'migrations') {
+} else if (subName === 'migrations') {
   const { migrationsCommand } = require('../lib/migrations-commands');
-  migrationsCommand(process.argv.slice(3)).catch(err => {
+  migrationsCommand(subArgs).catch(err => {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });

package/lib/completion/bash.template

@@ -89,7 +89,7 @@ _quilltap_complete() {
       return
       ;;
     --sort)
-      COMPREPLY=($(compgen -W "name path size modified created reinforced importance accessed reinforcement-count links" -- "$cur"))
+      COMPREPLY=($(compgen -W "name time size links reinforced importance created accessed reinforcement-count" -- "$cur"))
       return
       ;;
     --field)
@@ -109,10 +109,10 @@ _quilltap_complete() {
   # Subcommand-specific completion
   case "$subcommand" in
     db)
-      local db_verbs="schema find chats messages logs message log memories optimize backup integrity"
+      local db_verbs="schema find chats messages logs message log memories characters optimize backup integrity"
       local db_flags="--instance --data-dir --passphrase --json --limit --grep \
         --character --project --about --source --chat --message --rendered --field \
-        --tail --last --full --from --type --out --help \
+        --tail --last --full --from --type --out --id --diverged --blocked --help \
         --tables --count --repl --llm-logs --mount-points \
         --lock-status --lock-clean --lock-override"
       if [[ -z "$subverb" ]]; then
@@ -126,7 +126,7 @@ _quilltap_complete() {
       fi
       ;;
     docs)
-      local docs_verbs="list show files ls dir read export scan write delete mkdir move copy status find grep reindex embed"
+      local docs_verbs="list show files ls dir tree read export scan write delete mkdir move copy status find grep reindex embed"
       local docs_flags="--mount --instance --data-dir --passphrase --port --json --help \
         --force --rendered --links --folder --type --ext --limit --max --context --top --threshold \
         --ignore-case -l --wait -R --recursive --sort -r --reverse --depth --max-nodes --long --semantic"

package/lib/completion/fish.template

@@ -85,6 +85,7 @@ complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'logs' -d 'Get LL
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'message' -d 'Get single message'
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'log' -d 'Get single log entry'
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'memories' -d 'List memories'
+complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'characters' -d 'Per-character vault status'
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'optimize' -d 'Optimize database'
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'backup' -d 'Backup database'
 complete -c quilltap -n '__quilltap_using_subcommand db' -f -a 'integrity' -d 'Check integrity'
@@ -114,6 +115,9 @@ complete -c quilltap -n '__quilltap_using_subcommand db' -l 'mount-points' -d 'T
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'lock-status' -d 'Show instance lock status'
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'lock-clean' -d 'Clean stale lock'
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'lock-override' -d 'Override active lock'
+complete -c quilltap -n '__quilltap_using_subcommand db' -l 'id' -d 'Single character by name or id' -x
+complete -c quilltap -n '__quilltap_using_subcommand db' -l 'diverged' -d 'Only diverged characters'
+complete -c quilltap -n '__quilltap_using_subcommand db' -l 'blocked' -d 'Only characters with vault issues'
 
 # ---------- docs verbs ----------
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'list' -d 'List mount points'
@@ -121,6 +125,7 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'show' -d 'Show
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'files' -d 'List files in mount'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'ls' -d 'ls-style listing'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'dir' -d 'Directory listing'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'tree' -d 'ASCII tree view'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'read' -d 'Print file contents'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'export' -d 'Export mount'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -f -a 'scan' -d 'Trigger rescan'
@@ -153,7 +158,7 @@ complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'ignore-case' -d '
 complete -c quilltap -n '__quilltap_using_subcommand docs' -s 'l' -d 'Paths only'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'wait' -d 'Wait for completion'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'recursive' -s 'R' -d 'Recursive listing'
-complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'sort' -d 'Sort field' -x -a 'name path size modified created'
+complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'sort' -d 'Sort field' -x -a 'name time size links'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'reverse' -s 'r' -d 'Reverse sort order'
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'depth' -d 'Maximum traversal depth' -x
 complete -c quilltap -n '__quilltap_using_subcommand docs' -l 'max-nodes' -d 'Maximum graph nodes' -x

package/lib/completion/zsh.template

@@ -93,6 +93,7 @@ _quilltap_db() {
     'message:Get a single message'
     'log:Get a single LLM log entry'
     'memories:List memories for a character'
+    'characters:Per-character vault status report'
     'optimize:Optimize database'
     'backup:Backup database'
     'integrity:Check database integrity'
@@ -119,6 +120,9 @@ _quilltap_db() {
     '--from[Participant filter]:participant:'
     '--type[Filter by type]:type:'
     '--out[Output directory]:path:_files -/'
+    '--id[Single character by name or id]:character:'
+    '--diverged[Only characters whose DB and vault differ]'
+    '--blocked[Only characters with vault issues]'
     '--tables[List tables (low-level)]'
     '--count[Count rows in table]:table:'
     '--repl[Open SQL REPL]'
@@ -144,6 +148,7 @@ _quilltap_docs() {
     'files:List files in a mount'
     'ls:ls-style listing'
     'dir:Directory listing'
+    'tree:ASCII tree view of a folder'
     'read:Print file contents'
     'export:Export mount to directory'
     'scan:Trigger rescan'
@@ -181,7 +186,7 @@ _quilltap_docs() {
     '-l[Paths only]'
     '--wait[Wait for completion]'
     '(-R --recursive)'{-R,--recursive}'[Recursive listing]'
-    '--sort[Sort field]:field:(name path size modified created)'
+    '--sort[Sort field]:field:(name time size links)'
     '(-r --reverse)'{-r,--reverse}'[Reverse sort order]'
     '--depth[Maximum traversal depth]:n:'
     '--max-nodes[Maximum nodes in graph]:n:'

package/lib/db-commands.js

@@ -10,6 +10,8 @@ const {
   UUID_RE,
   ambiguous,
   resolveCharacter,
+  resolveCharactersByAlias,
+  readVaultAliases,
   resolveChat,
   resolveProject,
 } = require('./db-helpers');
@@ -318,21 +320,56 @@ function cmdFind(args, ctx) {
 }
 
 function findCharacters(query, { json, limit, ctx }) {
+  // Aliases live in each character's vault `properties.json` post-4.6, not on
+  // the `characters` row, so name matching comes from the main DB and alias
+  // matching/display comes from the mount-index DB.
   const db = ctx.openMain();
+  let mounts = null;
   try {
+    mounts = ctx.openMounts();
+  } catch {
+    mounts = null; // mount-index DB absent — name-only matching, no aliases
+  }
+  try {
+    const SELECT_COLS =
+      'SELECT id, name, npc, isFavorite, controlledBy, characterDocumentMountPointId AS mp FROM characters';
     let rows;
     if (!query) {
-      rows = db.prepare('SELECT id, name, npc, isFavorite, controlledBy FROM characters ORDER BY name LIMIT ?').all(limit);
+      rows = db.prepare(`${SELECT_COLS} ORDER BY name LIMIT ?`).all(limit);
     } else if (UUID_RE.test(query)) {
-      rows = db.prepare('SELECT id, name, npc, isFavorite, controlledBy, aliases FROM characters WHERE id = ?').all(query);
+      rows = db.prepare(`${SELECT_COLS} WHERE id = ?`).all(query);
     } else {
-      rows = db.prepare(
-        'SELECT id, name, npc, isFavorite, controlledBy, aliases FROM characters WHERE LOWER(name) LIKE LOWER(?) OR LOWER(aliases) LIKE LOWER(?) ORDER BY name LIMIT ?'
-      ).all(`%${query}%`, `%${query}%`, limit);
+      const byName = db
+        .prepare(`${SELECT_COLS} WHERE LOWER(name) LIKE LOWER(?) ORDER BY name`)
+        .all(`%${query}%`);
+      const seen = new Set(byName.map((r) => r.id));
+      rows = [...byName];
+      // Fold in alias matches from the vault, then re-fetch their rows so the
+      // output columns stay uniform.
+      for (const m of resolveCharactersByAlias(db, mounts, query)) {
+        if (seen.has(m.id)) continue;
+        seen.add(m.id);
+        const r = db.prepare(`${SELECT_COLS} WHERE id = ?`).get(m.id);
+        if (r) rows.push(r);
+      }
+      rows = rows.slice(0, limit);
     }
-    if (json) return printJson(rows);
-    printTable(rows);
+
+    // Attach vault-sourced aliases for display and drop the internal mount id.
+    const enriched = rows.map(({ mp, ...rest }) => ({
+      ...rest,
+      aliases: readVaultAliases(mounts, mp),
+    }));
+
+    if (json) return printJson(enriched);
+    printTable(
+      enriched.map((r) => ({
+        ...r,
+        aliases: r.aliases.length ? r.aliases.join(', ') : '',
+      })),
+    );
   } finally {
+    if (mounts) { try { mounts.close(); } catch {} }
     db.close();
   }
 }
@@ -388,7 +425,7 @@ function cmdChats(args, ctx) {
   try {
     let rows;
     if (flags.character) {
-      const c = resolveCharacter(db, String(flags.character));
+      const c = resolveCharacter(db, String(flags.character), ctx.openMounts);
       rows = db.prepare(
         "SELECT id, title, chatType, messageCount, lastMessageAt, projectId " +
         "FROM chats WHERE participants LIKE ? ORDER BY lastMessageAt DESC LIMIT ?"
@@ -488,7 +525,7 @@ function cmdLogs(args, ctx) {
     } else if (flags.character) {
       const main = ctx.openMain();
       let c;
-      try { c = resolveCharacter(main, String(flags.character)); } finally { main.close(); }
+      try { c = resolveCharacter(main, String(flags.character), ctx.openMounts); } finally { main.close(); }
       rows = logsDb.prepare(
         'SELECT id, createdAt, type, provider, modelName, chatId, messageId, durationMs FROM llm_logs WHERE characterId = ? ORDER BY createdAt DESC LIMIT ?'
       ).all(c.id, limit);
@@ -605,11 +642,11 @@ function cmdMemories(args, ctx) {
 
   const db = ctx.openMain();
   try {
-    const holder = resolveCharacter(db, String(flags.character));
+    const holder = resolveCharacter(db, String(flags.character), ctx.openMounts);
     const conditions = ['characterId = ?'];
     const params = [holder.id];
     if (flags.about) {
-      const a = resolveCharacter(db, String(flags.about));
+      const a = resolveCharacter(db, String(flags.about), ctx.openMounts);
       conditions.push('aboutCharacterId = ?');
       params.push(a.id);
     }
@@ -645,18 +682,33 @@ 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 = [
+// Single-file vault documents the character-properties overlay manages. Must
+// stay in sync with `CHARACTER_VAULT_DESCRIPTORS` in
+// lib/database/repositories/vault-overlay/. Post-4.6-cutover the vault is the
+// only home for these fields.
+//
+// REQUIRED files are written unconditionally by `writeCharacterVaultManagedFields`
+// (empty string when the field is blank), so a healthy character always has all
+// of them. The physical-* pair is OPTIONAL: the writer skips both when the
+// character has no physicalDescription. It writes them as a pair, so having
+// exactly one of the two is an inconsistency worth flagging.
+const REQUIRED_VAULT_SINGLE_FILES = [
   'properties.json',
   'identity.md',
   'description.md',
-  'manifesto.md',
   'personality.md',
   'example-dialogues.md',
+];
+// manifesto is nullable/optional. The full-projection writer writes an empty
+// manifesto.md when the field is blank, but the patch-level write overlay only
+// writes it when a patch carries a `manifesto` key — so a perfectly valid
+// character can simply lack the file. On read, absent == empty == null, so we
+// report manifesto's presence but never count its absence as "missing" or let
+// it block. (Treated like the physical-* pair: optional, surfaced, not required.)
+const OPTIONAL_VAULT_SINGLE_FILES = [
+  'manifesto.md',
+];
+const PHYSICAL_VAULT_FILES = [
   'physical-description.md',
   'physical-prompts.json',
 ];
@@ -695,8 +747,11 @@ function inspectCharacterVault(row, mounts) {
     mountPointId: row.characterDocumentMountPointId || null,
     vault: 'missing',
     presentSingleFiles: 0,
-    expectedSingleFiles: EXPECTED_VAULT_SINGLE_FILES.length,
+    expectedSingleFiles: REQUIRED_VAULT_SINGLE_FILES.length,
     missingSingleFiles: [],
+    manifestoPresent: false,   // optional single file: present or not, both valid
+    physicalFilesPresent: 0,   // 0, 1, or 2 of the optional physical-* pair
+    physicalInconsistent: false,
     promptsVault: 0,
     promptsDb: 0,
     scenariosVault: 0,
@@ -729,7 +784,7 @@ function inspectCharacterVault(row, mounts) {
     byPath.set(link.relativePath.toLowerCase(), link);
   }
 
-  for (const p of EXPECTED_VAULT_SINGLE_FILES) {
+  for (const p of REQUIRED_VAULT_SINGLE_FILES) {
     if (byPath.has(p)) {
       status.presentSingleFiles++;
     } else {
@@ -737,6 +792,14 @@ function inspectCharacterVault(row, mounts) {
     }
   }
 
+  // Manifesto is optional: report presence, never require it.
+  status.manifestoPresent = OPTIONAL_VAULT_SINGLE_FILES.every((p) => byPath.has(p));
+
+  // Physical-* files are optional (a character may legitimately have no
+  // physical description). Both-or-neither is healthy; exactly one is not.
+  status.physicalFilesPresent = PHYSICAL_VAULT_FILES.filter((p) => byPath.has(p)).length;
+  status.physicalInconsistent = status.physicalFilesPresent === 1;
+
   for (const [p] of byPath) {
     if (p.startsWith('prompts/') && p.endsWith('.md')) status.promptsVault++;
     else if (p.startsWith('scenarios/') && p.endsWith('.md')) status.scenariosVault++;
@@ -835,10 +898,18 @@ function inspectCharacterVault(row, mounts) {
     }
   }
 
-  if (status.missingSingleFiles.length === EXPECTED_VAULT_SINGLE_FILES.length) {
+  const anyContent = status.presentSingleFiles > 0
+    || status.manifestoPresent
+    || status.physicalFilesPresent > 0
+    || status.promptsVault > 0
+    || status.scenariosVault > 0
+    || status.wardrobeVault > 0;
+  if (!anyContent) {
     status.issue = 'vault empty';
   } else if (status.missingSingleFiles.length > 0) {
-    status.issue = `${status.missingSingleFiles.length} files missing`;
+    status.issue = `${status.missingSingleFiles.length} required files missing`;
+  } else if (status.physicalInconsistent) {
+    status.issue = 'physical files incomplete (1 of 2)';
   } else if (status.diverged.length > 0) {
     status.issue = `diverged (${status.diverged.length})`;
   } else if (!preCutover) {
@@ -886,7 +957,7 @@ function cmdCharacters(args, ctx) {
     let sql = `SELECT ${cols.join(', ')} FROM characters`;
     const params = [];
     if (idQuery) {
-      const c = resolveCharacter(main, idQuery);
+      const c = resolveCharacter(main, idQuery, ctx.openMounts);
       sql += ' WHERE id = ?';
       params.push(c.id);
     } else {
@@ -920,22 +991,32 @@ function cmdCharacters(args, ctx) {
     }
 
     const summary = summarizeCharacterStatuses(all);
-    const headline = `Scanned ${all.length} character${all.length === 1 ? '' : 's'}: ` +
+    let 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.`;
+      `${summary.noVault} with no vault, ${summary.empty} empty`;
+    if (summary.physIncomplete > 0) headline += `, ${summary.physIncomplete} with incomplete physical files`;
+    headline += '.';
     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),
-    })));
+    // The readPropertiesFromDocumentStore flag and the DB side of the
+    // prompts/scenarios counts only exist before the 4.6 cutover. Post-cutover
+    // (the normal case now) the vault is canonical, so drop the dead `flag`
+    // column and show vault-only counts instead of misleading `vault/db`.
+    const anyPreCutover = all.some(s => s.preCutover);
+    printTable(filtered.map(s => {
+      const missing = s.vault === 'missing';
+      const row = { id: s.id.slice(0, 8), name: truncate(s.name, 28) };
+      if (anyPreCutover) row.flag = s.flag == null ? '-' : s.flag;
+      row.vault = s.vault;
+      row.files = missing ? '-' : `${s.presentSingleFiles}/${s.expectedSingleFiles}`;
+      row.manifesto = missing ? '-' : (s.manifestoPresent ? 'yes' : 'no');
+      row.phys = missing ? '-' : `${s.physicalFilesPresent}/2`;
+      row.prompts = missing ? '-' : (anyPreCutover ? `${s.promptsVault}/${s.promptsDb}` : String(s.promptsVault));
+      row.scenarios = missing ? '-' : (anyPreCutover ? `${s.scenariosVault}/${s.scenariosDb}` : String(s.scenariosVault));
+      row.wardrobe = missing ? '-' : s.wardrobeVault;
+      row.status = truncate(s.issue, 60);
+      return row;
+    }));
 
     if (filtered.length > 0 && filtered.some(s => s.diverged.length > 0)) {
       console.log('');
@@ -948,16 +1029,17 @@ function cmdCharacters(args, ctx) {
 }
 
 function summarizeCharacterStatuses(all) {
-  let ok = 0, diverged = 0, missingFiles = 0, noVault = 0, empty = 0;
+  let ok = 0, diverged = 0, missingFiles = 0, noVault = 0, empty = 0, physIncomplete = 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('physical files incomplete')) physIncomplete++;
     else if (s.issue.startsWith('diverged')) diverged++;
   }
-  return { ok, diverged, missingFiles, noVault, empty };
+  return { ok, diverged, missingFiles, noVault, empty, physIncomplete };
 }
 
 // ---------- verb: optimize ----------

package/lib/db-helpers.js

@@ -255,25 +255,104 @@ function ambiguous(kind, rows) {
   return err;
 }
 
-function resolveCharacter(db, query) {
+// Read the `aliases` array out of a character vault's `properties.json`.
+// The 4.6 vault cutover dropped the `aliases` (and `pronouns`) columns from
+// the `characters` table — they now live only in the per-character vault — so
+// any alias lookup has to go through the mount-index DB. `mounts` is that
+// handle; `mountPointId` is `characters.characterDocumentMountPointId`.
+// Returns [] for a missing/empty/unparseable vault so callers can treat the
+// absence of aliases as "no match" rather than an error.
+function readVaultAliases(mounts, mountPointId) {
+  if (!mounts || !mountPointId) return [];
+  const rec = mounts.prepare(
+    `SELECT d.content AS content
+       FROM doc_mount_file_links l
+       JOIN doc_mount_documents d ON d.fileId = l.fileId
+      WHERE l.mountPointId = ? AND LOWER(l.relativePath) = 'properties.json'
+      LIMIT 1`
+  ).get(mountPointId);
+  if (!rec || !rec.content) return [];
+  try {
+    const props = JSON.parse(rec.content);
+    return Array.isArray(props.aliases)
+      ? props.aliases.filter((a) => typeof a === 'string')
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+// Find characters whose vault aliases contain `query` (case-insensitive
+// substring). Requires a mount-index DB handle; returns [{ id, name }].
+// Scans every vaulted character's `properties.json` — fine for a CLI, and only
+// reached on the fuzzy-resolution fallback (a clean name match returns first).
+function resolveCharactersByAlias(db, mounts, query) {
+  if (!mounts) return [];
+  const needle = query.toLowerCase();
+  const chars = db.prepare(
+    'SELECT id, name, characterDocumentMountPointId AS mp FROM characters WHERE characterDocumentMountPointId IS NOT NULL'
+  ).all();
+  const matches = [];
+  for (const c of chars) {
+    const aliases = readVaultAliases(mounts, c.mp);
+    if (aliases.some((a) => a.toLowerCase().includes(needle))) {
+      matches.push({ id: c.id, name: c.name });
+    }
+  }
+  return matches;
+}
+
+// Resolve a UUID / name / alias to a single { id, name } row.
+//
+// `openMounts` (optional) is a zero-arg function that returns a mount-index DB
+// handle (e.g. `ctx.openMounts`). When supplied, the fuzzy fallback also
+// matches against vault-stored aliases; when omitted (or if the mount-index DB
+// can't be opened), resolution degrades gracefully to UUID + name only.
+function resolveCharacter(db, query, openMounts = null) {
   if (UUID_RE.test(query)) {
-    const row = db.prepare('SELECT id, name, aliases FROM characters WHERE id = ?').get(query);
+    const row = db.prepare('SELECT id, name FROM characters WHERE id = ?').get(query);
     if (!row) throw new Error(`No character with id ${query}`);
     return row;
   }
   const exact = db.prepare(
-    'SELECT id, name, aliases FROM characters WHERE LOWER(name) = LOWER(?)'
+    'SELECT id, name FROM characters WHERE LOWER(name) = LOWER(?)'
   ).all(query);
   if (exact.length === 1) return exact[0];
   if (exact.length > 1) {
     throw ambiguous('character', exact);
   }
-  const fuzzy = db.prepare(
-    'SELECT id, name, aliases FROM characters WHERE LOWER(name) LIKE LOWER(?) OR LOWER(aliases) LIKE LOWER(?) ORDER BY name'
-  ).all(`%${query}%`, `%${query}%`);
-  if (fuzzy.length === 0) throw new Error(`No character matching '${query}'`);
-  if (fuzzy.length > 1) throw ambiguous('character', fuzzy);
-  return fuzzy[0];
+
+  const candidates = db.prepare(
+    'SELECT id, name FROM characters WHERE LOWER(name) LIKE LOWER(?) ORDER BY name'
+  ).all(`%${query}%`);
+
+  // Fold in alias matches from the vault when the caller gave us a way to
+  // reach the mount-index DB. Aliases moved into properties.json in 4.6.
+  if (openMounts) {
+    let mounts = null;
+    try {
+      mounts = openMounts();
+    } catch {
+      mounts = null; // mount-index DB absent on this instance — skip aliases
+    }
+    if (mounts) {
+      try {
+        const seen = new Set(candidates.map((r) => r.id));
+        for (const m of resolveCharactersByAlias(db, mounts, query)) {
+          if (!seen.has(m.id)) {
+            seen.add(m.id);
+            candidates.push(m);
+          }
+        }
+      } finally {
+        try { mounts.close(); } catch {}
+      }
+    }
+  }
+
+  if (candidates.length === 0) throw new Error(`No character matching '${query}'`);
+  if (candidates.length > 1) throw ambiguous('character', candidates);
+  return candidates[0];
 }
 
 function resolveChat(db, query) {
@@ -317,6 +396,8 @@ module.exports = {
   UUID_RE,
   ambiguous,
   resolveCharacter,
+  resolveCharactersByAlias,
+  readVaultAliases,
   resolveChat,
   resolveProject,
 };

package/lib/memories-commands.js

@@ -5,6 +5,7 @@ const {
   printDefaultInstanceHint,
   loadDbKey,
   openMainDb,
+  openMountIndexDb,
   UUID_RE,
   resolveCharacter,
   resolveChat,
@@ -179,7 +180,10 @@ async function openDb(flags) {
   const { dataDir, passphrase } = resolved;
   const pepper = await loadDbKey(dataDir, passphrase);
   const db = openMainDb(dataDir, pepper, { readonly: true });
-  return { db, dataDir };
+  // Lazy opener for the mount-index DB so `resolveCharacter` can match
+  // vault-stored aliases (4.6 cutover moved them out of the `characters` row).
+  const openMounts = () => openMountIndexDb(dataDir, pepper, { readonly: true });
+  return { db, dataDir, openMounts };
 }
 
 // ---------- filter / sort builders ----------
@@ -188,13 +192,13 @@ async function openDb(flags) {
 // `{ where: 'WHERE m.x = ? AND ...', params: [...], meta: { characterId, ... } }`.
 // `meta` exposes resolved IDs so callers can decide e.g. whether to show a
 // per-row holder column.
-function buildWhereClause(db, flags) {
+function buildWhereClause(db, flags, openMounts = null) {
   const clauses = [];
   const params = [];
   const meta = { characterId: null, aboutId: null, chatId: null, projectId: null, allCharacters: true };
 
   if (flags.character && flags.character !== 'all') {
-    const c = resolveCharacter(db, flags.character);
+    const c = resolveCharacter(db, flags.character, openMounts);
     clauses.push('m.characterId = ?');
     params.push(c.id);
     meta.characterId = c.id;
@@ -207,7 +211,7 @@ function buildWhereClause(db, flags) {
     } else if (flags.about === 'none') {
       clauses.push('m.aboutCharacterId IS NULL');
     } else {
-      const a = resolveCharacter(db, flags.about);
+      const a = resolveCharacter(db, flags.about, openMounts);
       clauses.push('m.aboutCharacterId = ?');
       params.push(a.id);
       meta.aboutId = a.id;
@@ -395,9 +399,9 @@ function renderJson(obj) {
 // ---------- ls ----------
 
 async function cmdLs(flags) {
-  const { db } = await openDb(flags);
+  const { db, openMounts } = await openDb(flags);
   try {
-    const { where, params, meta } = buildWhereClause(db, flags);
+    const { where, params, meta } = buildWhereClause(db, flags, openMounts);
     const { order, impField } = buildOrderBy(flags.sort, flags.reverse);
     const limit = flags.limit > 0 ? flags.limit : 50;
     const sql = `${SELECT_BASE} ${where} ORDER BY ${order} LIMIT ?`;
@@ -512,9 +516,9 @@ async function cmdFind(flags, positional) {
   if (!['summary', 'content', 'both'].includes(inWhere)) {
     throw new Error(`--in must be one of: summary, content, both (got '${inWhere}')`);
   }
-  const { db } = await openDb(flags);
+  const { db, openMounts } = await openDb(flags);
   try {
-    const { where, params, meta } = buildWhereClause(db, flags);
+    const { where, params, meta } = buildWhereClause(db, flags, openMounts);
     const like = `%${pattern}%`;
 
     const matchClauses = [];
@@ -584,9 +588,9 @@ async function cmdSemanticGrep(flags, query) {
   // Resolve character locally so the server gets a stable UUID.
   let characterId;
   {
-    const { db } = await openDb(flags);
+    const { db, openMounts } = await openDb(flags);
     try {
-      const resolved = resolveCharacter(db, flags.character);
+      const resolved = resolveCharacter(db, flags.character, openMounts);
       characterId = resolved.id;
     } finally {
       db.close();
@@ -675,9 +679,9 @@ async function cmdGrep(flags, positional) {
   if (flags.semantic) {
     return cmdSemanticGrep(flags, pattern);
   }
-  const { db } = await openDb(flags);
+  const { db, openMounts } = await openDb(flags);
   try {
-    const { where, params } = buildWhereClause(db, flags);
+    const { where, params } = buildWhereClause(db, flags, openMounts);
     // Always restrict to rows whose content can match — quick pre-filter so we
     // don't read all 32k rows into JS just to drop most of them.
     const likeNeedle = flags.ignoreCase ? `%${pattern.toLowerCase()}%` : `%${pattern}%`;
@@ -1044,11 +1048,11 @@ function graphToJson(node) {
 // ---------- status ----------
 
 async function cmdStatus(flags) {
-  const { db } = await openDb(flags);
+  const { db, openMounts } = await openDb(flags);
   try {
     let holderRows;
     if (flags.character && flags.character !== 'all') {
-      const c = resolveCharacter(db, flags.character);
+      const c = resolveCharacter(db, flags.character, openMounts);
       holderRows = [{ id: c.id, name: c.name }];
     } else {
       holderRows = db.prepare(`
@@ -1180,12 +1184,12 @@ function renderStatusBlock(holder, stats) {
 // ---------- validate ----------
 
 async function cmdValidate(flags) {
-  const { db } = await openDb(flags);
+  const { db, openMounts } = await openDb(flags);
   try {
     let holderIds = null;
     let holderRows;
     if (flags.character && flags.character !== 'all') {
-      const c = resolveCharacter(db, flags.character);
+      const c = resolveCharacter(db, flags.character, openMounts);
       holderRows = [{ id: c.id, name: c.name }];
       holderIds = [c.id];
     } else {

package/lib/migrations-commands.js

@@ -26,7 +26,7 @@ function parseFlags(args) {
     const a = args[i];
     switch (a) {
       case '-d': case '--data-dir': flags.dataDir = args[++i]; break;
-      case '--instance': flags.instance = args[++i]; break;
+      case '-i': case '--instance': flags.instance = args[++i]; break;
       case '--passphrase': flags.passphrase = args[++i]; break;
       case '--json': flags.json = true; break;
       case '-h': case '--help': flags.help = true; break;
@@ -118,7 +118,7 @@ Commands:
 
 Options:
   -d, --data-dir <path>     Use a specific data directory
-  --instance <name>         Use a named instance
+  -i, --instance <name>     Use a named instance
   --passphrase <pass>       Provide passphrase (prompts if needed)
   --json                    Output as JSON
   -h, --help                Show this help message

package/lib/native-modules.js

@@ -21,6 +21,48 @@ function resolveModuleDir(moduleName) {
   }
 }
 
+// node-pty needs a `spawn-helper` executable beside the pty.node it loads, or
+// pty.spawn() fails with `posix_spawnp failed`. An ABI rebuild lands a fresh
+// build/Release/pty.node (which node-pty's loader prefers over prebuilds/) but
+// emits only the addon, not node-pty's separate spawn-helper target; tar/extract
+// can also drop the exec bit on the shipped prebuilds/*/spawn-helper. spawn-helper
+// is a plain executable (no Node linkage) so the prebuilt copy is ABI-independent
+// and safe to reuse. Best-effort; never throws.
+function reconcileNodePtySpawnHelper() {
+  if (process.platform === 'win32') return; // conpty has no spawn-helper
+  const fs = require('fs');
+  try {
+    const nodePtyDir = resolveModuleDir('node-pty');
+    if (!nodePtyDir) return;
+    const prebuildsDir = path.join(nodePtyDir, 'prebuilds');
+    const prebuiltHelper = path.join(prebuildsDir, `${process.platform}-${process.arch}`, 'spawn-helper');
+
+    if (fs.existsSync(prebuildsDir)) {
+      for (const entry of fs.readdirSync(prebuildsDir)) {
+        const helper = path.join(prebuildsDir, entry, 'spawn-helper');
+        if (fs.existsSync(helper)) {
+          try { fs.chmodSync(helper, 0o755); } catch { /* best-effort */ }
+        }
+      }
+    }
+
+    for (const buildType of ['Release', 'Debug']) {
+      const buildDir = path.join(nodePtyDir, 'build', buildType);
+      const builtAddon = path.join(buildDir, 'pty.node');
+      const builtHelper = path.join(buildDir, 'spawn-helper');
+      if (fs.existsSync(builtHelper)) {
+        try { fs.chmodSync(builtHelper, 0o755); } catch { /* best-effort */ }
+      } else if (fs.existsSync(builtAddon) && fs.existsSync(prebuiltHelper)) {
+        fs.copyFileSync(prebuiltHelper, builtHelper);
+        fs.chmodSync(builtHelper, 0o755);
+        console.log(`  node-pty: backfilled build/${buildType}/spawn-helper from prebuilds`);
+      }
+    }
+  } catch {
+    // best-effort — node-pty terminals are optional; never block the CLI
+  }
+}
+
 // Check if native modules are compiled for the current Node.js version.
 // This handles the case where npx caches the package but the user upgrades
 // Node.js — the cached native modules will have a stale NODE_MODULE_VERSION.
@@ -73,7 +115,10 @@ function ensureNativeModules() {
     }
   }
 
-  if (needsRebuild.length === 0) return true;
+  if (needsRebuild.length === 0) {
+    reconcileNodePtySpawnHelper();
+    return true;
+  }
 
   console.log(`  Rebuilding native modules for Node.js ${process.version}...`);
 
@@ -84,6 +129,7 @@ function ensureNativeModules() {
     });
     console.log('  Done.');
     console.log('');
+    reconcileNodePtySpawnHelper();
     return true;
   } catch (err) {
     console.error('');
@@ -94,7 +140,7 @@ function ensureNativeModules() {
   }
 }
 
-module.exports = { resolveModuleDir, ensureNativeModules, PACKAGE_DIR };
+module.exports = { resolveModuleDir, ensureNativeModules, reconcileNodePtySpawnHelper, PACKAGE_DIR };
 
 // Allow this file to be invoked directly as a postinstall script:
 //   node lib/native-modules.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.6.0-dev.99",
+  "version": "4.6.0",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",
@@ -40,8 +40,8 @@
     "better-sqlite3-multiple-ciphers": "^12.10.0",
     "node-pty": "^1.1.0",
     "sharp": "^0.34.5",
-    "tar": "^7.5.15",
-    "yauzl": "^3.3.1"
+    "tar": "^7.5.16",
+    "yauzl": "^3.3.2"
   },
   "engines": {
     "node": ">=24.0.0"