@vodmal/vdx-cli 0.37.1 → 0.39.0

package/README.md

@@ -50,11 +50,14 @@ vdx push [project-path] [--dry-run]   # default: cwd
 
 # Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project; the GitHub token vdx asks with)
 vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
+vdx doctor --staged                 # pre-commit guard: Claude Code memory goes into a commit only where nobody but
+                                    # you reads every place it reaches (origin, mirrors; GitHub asked with gh's token)
 vdx doctor --check [project-path]   # one line per hook declared but not running here, and one when the memory is
                                     # not inside — the plugin's SessionStart hook tells the agent
 vdx doctor --fix [project-path]     # write the profile's personal hooks (git.hooks) into ~/.gitconfig, and put
                                     # the project's Claude Code memory inside it: .claude/memory/ (after a
-                                    # folder move, its path and conversations follow)
+                                    # folder move, its path and conversations follow; notes a session that
+                                    # started before the move wrote at the old place come in)
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
 vdx ai[@host] [project-path] [--new | --conversation <id>] [--focused | --intercom] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there; --intercom: the project's mail session
@@ -114,7 +117,8 @@ The session's `{project}` is `[_.vdx] name` (or the older `[vdx]`) from the proj
 first file in the profile's `session.project_names` that has one, else the repo
 name. `vdx ai@<host>` runs the same command on `<host>` over ssh — that machine's vdx,
 profile and tmux, the path taken under its home directory; `--detach` only
-starts it. The machine's own label (`$VDX_HOST`) runs here. Where git knows no
+starts it, and not in a folder Claude Code does not trust yet: nobody would answer
+its trust window (exit 4; start once without `--detach`). The machine's own label (`$VDX_HOST`) runs here. Where git knows no
 commit author, `vdx ai` proposes one (Enter writes it into `.git/config`).
 For Claude Code `vdx ai` picks the conversation: each one is marked with the
 machine it was last started on (`vdx ai --check`, run by the plugin's hook, writes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.37.1",
+  "version": "0.39.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.3"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "1.7.0"
+  version: "1.8.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"

package/src/ai.ts

@@ -10,6 +10,7 @@ import { loadManifestAt } from './manifest.ts';
 import { type Author, effectiveAuthor, isGitRepo, rankAuthors, scanPool, writeAuthor } from './author.ts';
 import type { Predicate } from './rubric.ts';
 import {
+  claudeTrusts,
   type Conversation,
   describeConversation,
   describeAge,
@@ -29,7 +30,15 @@ import {
   parseMachineReport,
   runsInProject,
 } from './conversations.ts';
-import { describeMemory, fixProjectMemory, memoryNeedsFix, memoryState } from './memory.ts';
+import {
+  describeMemory,
+  fixProjectMemory,
+  memoryApplies,
+  memoryNeedsFix,
+  memoryState,
+  personalHosts,
+  type PersonalHost,
+} from './memory.ts';
 import { at, errorMessage, isStringList, str } from './narrow.ts';
 import { type Lag, sessionLag } from './session-versions.ts';
 
@@ -116,8 +125,11 @@ interface GitProfile {
   /** Directories whose repos are the neighbours an author is proposed from; default — the project's parent. */
   author_pool?: string[];
   hooks?: PersonalHook[];
-  /** Hosts whose repos are the owner's alone: Claude Code's memory goes under git there (claude-memory-in-project). */
-  personal_hosts?: string[];
+  /**
+   * Hosts whose repos are the owner's alone, and where their repos are mirrored: Claude Code's
+   * memory goes under git only where nobody else reads (claude-memory-in-project).
+   */
+  personal_hosts?: Array<string | { host: string; mirrors?: string[] }>;
 }
 
 export interface Environment {
@@ -255,8 +267,21 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (gitDoc.author_pool !== undefined && !isStringList(gitDoc.author_pool)) {
       fail('git.author_pool', 'must be a list of directories');
     }
-    if (gitDoc.personal_hosts !== undefined && !isStringList(gitDoc.personal_hosts)) {
-      fail('git.personal_hosts', 'must be a list of host names');
+    if (gitDoc.personal_hosts !== undefined) {
+      if (!Array.isArray(gitDoc.personal_hosts)) fail('git.personal_hosts', 'must be a list');
+      gitDoc.personal_hosts.forEach((h, i) => {
+        const at = `git.personal_hosts[${i}]`;
+        if (typeof h === 'string') {
+          if (h.trim() === '') fail(at, 'must be a host name');
+          return;
+        }
+        if (typeof h !== 'object' || h === null || typeof h.host !== 'string' || h.host.trim() === '') {
+          fail(at, 'must be a host name, or a mapping with host');
+        }
+        if (h.mirrors !== undefined && (!isStringList(h.mirrors) || !h.mirrors.every((m) => m.includes('{repo}')))) {
+          fail(`${at}.mirrors`, 'must be a list of places like github.com/<owner>/{repo}');
+        }
+      });
     }
     if (gitDoc.hooks !== undefined) {
       if (!Array.isArray(gitDoc.hooks)) fail('git.hooks', 'must be a list');
@@ -1157,13 +1182,13 @@ export function ensureAuthor(projectRoot: string, poolDirs: string[], deps: AiDe
 export function ensureMemory(
   projectRoot: string,
   command: string,
-  personalHosts: string[],
+  hosts: PersonalHost[],
   deps: AiDeps,
   dryRun: boolean,
   agentRunning: boolean,
 ): void {
-  if (!isClaude(command)) return;
   const ctx = { env: deps.env, home: deps.home };
+  if (!isClaude(command) || !memoryApplies(projectRoot, ctx)) return;
   const state = memoryState(projectRoot, ctx);
   if (dryRun) {
     deps.out(`  memory:   ${describeMemory(state, ctx)}\n`);
@@ -1194,7 +1219,7 @@ export function ensureMemory(
       ask: deps.ask,
       log: deps.log,
       today: new Date().toLocaleDateString('sv-SE'),
-      personalHosts,
+      personalHosts: hosts,
     });
     for (const d of done) deps.log(`✓ ${d}`);
   } catch (e) {
@@ -1743,9 +1768,10 @@ export function runAiCheck(pathArg: string, deps: AiDeps, selfPid: number = proc
     `Hand the user the fix — ${reload}` +
       (deps.env['TMUX']
         ? `\`${vdxAi} --restart ${root}\`: it stops this session and starts it again${again}` +
-          // A focused session and the mail session restart into a new conversation.
+          // A focused session and the mail session restart into a new conversation, and what lives
+          // only in this one ends with it (ai-dev-plugins, restart-hint-wrap-first).
           (focused || intercom
-            ? ', in a new conversation'
+            ? ", in a new conversation — before handing it over, run the project's wrap check (`/vdm:wrap` where vdm is installed): what lives only in this chat ends with it"
             : plan.resumeArgs.length
               ? `, resuming the conversation (${plan.resumeArgs.join(' ')})`
               : '') +
@@ -1937,7 +1963,14 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     for (const l of choice?.lines ?? []) deps.out(`  conversation: ${l}\n`);
     for (const l of folders) deps.out(`  ${l}\n`);
     ensureAuthor(projectRoot, poolDirs, deps, true);
-    ensureMemory(projectRoot, plan.command, environment.git?.personal_hosts ?? [], deps, true, agentsHere.length > 0);
+    ensureMemory(
+      projectRoot,
+      plan.command,
+      personalHosts(environment.git?.personal_hosts),
+      deps,
+      true,
+      agentsHere.length > 0,
+    );
     return EXIT_OK;
   }
   for (const l of choice?.lines ?? []) log(l);
@@ -1973,7 +2006,14 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     plan = { ...plan, resumeArgs: resumeId(id) };
   }
   ensureAuthor(projectRoot, poolDirs, deps, false);
-  ensureMemory(projectRoot, plan.command, environment.git?.personal_hosts ?? [], deps, false, agentsHere.length > 0);
+  ensureMemory(
+    projectRoot,
+    plan.command,
+    personalHosts(environment.git?.personal_hosts),
+    deps,
+    false,
+    agentsHere.length > 0,
+  );
 
   if (multiplexer === 'none') {
     if (opts.restart) {
@@ -2064,6 +2104,14 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     if (live) plan = { ...plan, resumeArgs: resumeId(live) };
   }
 
+  // Nobody sits at a detached start, and Claude Code holds one in a folder it does not trust on
+  // its trust window, unseen (intercom-session-mode Sidetrack #4). The answer is the person's.
+  if (opts.detach && isClaude(plan.command) && claudeTrusts(projectRoot, deps.env, deps.home) === false) {
+    log(`✗ Claude Code has not trusted ${projectRoot} yet: a detached agent would wait on its trust window, unseen`);
+    log(`  start it once at a terminal and answer the window: ${vdxAiHere} ${shellQuote(projectRoot)}`);
+    return EXIT_LAUNCH_FAILED;
+  }
+
   if (current) {
     const line = agentLine(plan, [...plan.args, ...plan.resumeArgs]);
     log(`↻ ${current.pane.session} ${current.pane.paneId}: restarting — ${line}`);

package/src/conversations.ts

@@ -69,6 +69,41 @@ export function claudeConfigDir(env: NodeJS.ProcessEnv, home: string): string {
   return dir ? path.resolve(dir.replace(/^~(?=$|\/)/, home)) : path.join(home, '.claude');
 }
 
+/**
+ * Whether Claude Code trusts a folder (2.1.308, claude-memory-in-project DL #13): its global
+ * config, `.claude.json` in `CLAUDE_CONFIG_DIR` or the home directory, marks
+ * `projects[<folder>].hasTrustDialogAccepted` for the folder or one above it — inside a git
+ * checkout only up to the checkout's top. A start in a folder it does not trust stops on the
+ * trust window until somebody answers. Null: the config cannot be read, nobody knows.
+ */
+export function claudeTrusts(folder: string, env: NodeJS.ProcessEnv, home: string): boolean | null {
+  const dir = env['CLAUDE_CONFIG_DIR']?.trim();
+  let projects: Record<string, unknown> | undefined;
+  try {
+    const file = path.join(dir ? path.resolve(dir.replace(/^~(?=$|\/)/, home)) : home, '.claude.json');
+    projects = dict(at(JSON.parse(fs.readFileSync(file, 'utf8')), 'projects'));
+  } catch {
+    return null;
+  }
+  let d = path.resolve(folder);
+  try {
+    d = fs.realpathSync(d);
+  } catch {
+    // A folder that is not there is trusted by nothing but its own record.
+  }
+  let top: string | null = null;
+  for (let p = d; top === null; p = path.dirname(p)) {
+    if (fs.existsSync(path.join(p, '.git'))) top = p;
+    if (path.dirname(p) === p) break;
+  }
+  for (;;) {
+    if (at(projects?.[d.normalize('NFC')], 'hasTrustDialogAccepted') === true) return true;
+    const up = path.dirname(d);
+    if (d === top || up === d) return false;
+    d = up;
+  }
+}
+
 export function projectDirName(projectRoot: string): string {
   return projectRoot.replace(/[^A-Za-z0-9]/g, '-');
 }

package/src/doctor.ts

@@ -17,7 +17,10 @@ import { githubToken, machineIo, type HostingIo } from './hosting.ts';
 import {
   describeMemory,
   fixProjectMemory,
+  memoryApplies,
   memoryNeedsFix,
+  memoryReaders,
+  personalHosts,
   memoryState,
   type MemoryCtx,
   type MemoryState,
@@ -522,6 +525,7 @@ export function checkClaudeMemory(
   if (ctx.projectRoot === null || !claudeIsTheAgent(environment)) return null;
   // Claude Code's slot is the folder the agent starts in — the checkout's top for vdx ai.
   const root = resolveProjectRoot(ctx.projectRoot) ?? ctx.projectRoot;
+  if (!memoryApplies(root, mctx)) return null;
   const state = memoryState(root, mctx);
   return {
     id: 'claude-memory',
@@ -553,7 +557,19 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   (ctx) => checkClaudeMemory(ctx),
 ];
 
-export function resolveDoctorCtx(cwd: string = process.cwd()): DoctorCtx {
+/**
+ * The project doctor looks at: a directory named on the command line is one, whatever it
+ * holds — a folder of notes or of other repos has Claude Code memory too (avatar,
+ * l10inc, 2026-10-23); the working directory only with a project's marker file.
+ */
+export function resolveDoctorCtx(cwd: string = process.cwd(), named = false): DoctorCtx {
+  if (named) {
+    try {
+      if (fs.statSync(cwd).isDirectory()) return { projectRoot: cwd };
+    } catch {
+      /* no such directory: no project */
+    }
+  }
   return { projectRoot: looksLikeProject(cwd) ? cwd : null };
 }
 
@@ -609,10 +625,33 @@ export function fixDoctorMemory(
 ): string[] {
   return fixProjectMemory(projectRoot, state, memoryCtx(), {
     ...io,
-    personalHosts: profile().git?.personal_hosts ?? [],
+    personalHosts: personalHosts(profile().git?.personal_hosts),
   });
 }
 
+/**
+ * `vdx doctor --staged`, the profile's pre-commit hook: Claude Code's memory goes into a
+ * commit only where nobody but the owner reads every place the commit reaches
+ * (claude-memory-in-project DL #11, #12). Nothing staged under `.claude/memory/` — no word.
+ * Returns the refusal, or null to let the commit go.
+ */
+export function runDoctorStaged(
+  projectRoot: string,
+  io: HostingIo = machineIo(projectRoot),
+  environment: Environment = profile(),
+): string | null {
+  const staged = io.git(['diff', '--cached', '--name-only', '--', '.claude/memory']);
+  if (!staged) return null;
+  const readers = memoryReaders(io, personalHosts(environment.git?.personal_hosts));
+  if (readers.only) return null;
+  const n = staged.split('\n').length;
+  return (
+    `vdx doctor: Claude memory stays out of this commit (${n} file(s)) — ${readers.why}.\n` +
+    `  commit the rest: git restore --staged .claude/memory, and commit again\n` +
+    `  keep it out of git here: echo /.claude/memory/ >> "$(git rev-parse --git-path info/exclude)"`
+  );
+}
+
 const PROJECT_MARKER_FILES = [
   'package.json',
   'composer.json',

package/src/index.ts

@@ -19,6 +19,7 @@ import {
 import {
   checkClaudeMemory,
   fixDoctorMemory,
+  runDoctorStaged,
   runDoctor,
   runDoctorCheck,
   runDoctorFix,
@@ -128,7 +129,10 @@ the project's files). Hand a person \`vdx ai\`, not \`<agent> --<flag>\`.
                 Without it, an agent running without the profile's flags is
                 a question in a terminal: Enter attaches to it as is, r
                 restarts it, q leaves it
-  --detach      start without attaching; print the command that attaches
+  --detach      start without attaching; print the command that attaches. In a
+                folder Claude Code does not trust yet, nothing starts (exit 4):
+                its trust window would wait with nobody at it — start once
+                without --detach and answer it
   --dry-run     print the plan and the project's running agents; start nothing
   --check       for the agent's own session: how the agent here is launched,
                 whether this session carries the profile's flags, and whether it
@@ -234,9 +238,10 @@ or GitHub stopped answering; a plain git push exits with git's own code.
     positionals: 1,
   },
   doctor: {
-    usage: 'vdx doctor [project_path] [--check | --fix] [--format=ansi|markdown|json] [--json]',
+    usage: 'vdx doctor [project_path] [--check | --fix | --staged] [--format=ansi|markdown|json] [--json]',
     help: `Checks this machine for what vdx needs (Node, git, mise, npm auth, docker, the
-Claude Code plugin) and, inside a project (default: cwd), its commit author and
+Claude Code plugin) and, inside a project (default: cwd, when it looks like one; a
+folder named here is one, git or not — the home directory never), its commit author and
 its git hooks: are the hooks the repository declares on in this clone, and do
 the personal hooks of your profile (git.hooks) run on this machine; with origin on
 GitHub, the token vdx asks GitHub with ($GH_TOKEN, $GITHUB_TOKEN or gh) and
@@ -252,13 +257,22 @@ takes it along. Reads only, unless --fix. Exit 2 when something is missing.
            install step, which the report names); and put the memory inside:
            notes from ~/.claude/projects/<path>/memory into .claude/memory/, none
            overwritten, the old place renamed, autoMemoryDirectory written —
-           into .claude/settings.json in a personal project (no origin, or origin
-           on a host of git.personal_hosts), else into .claude/settings.local.json,
+           into .claude/settings.json in a personal project (only you read where
+           its commits go — see --staged), else into .claude/settings.local.json,
            with the memory kept out of git (.git/info/exclude) unless you say
            yes. After a folder is moved: the path follows it, and the project's
-           conversations move to the new path
+           conversations move to the new path; a folder Claude Code has not
+           trusted yet is named. Notes a session that started before the move
+           wrote at the old place come in, with their MEMORY.md lines; a path
+           another clone left in the shared settings.json goes, for this clone,
+           into its .claude/settings.local.json
+  --staged the profile's pre-commit hook: refuses a commit that stages
+           .claude/memory/ unless only you read every place the commit reaches —
+           origin on a host of git.personal_hosts or a private GitHub repo with
+           nobody else, and each mirror the profile names (GitHub asked with gh's
+           token); no answer, no token — refused. Silent otherwise
 `,
-    bools: ['json', 'check', 'fix'],
+    bools: ['json', 'check', 'fix', 'staged'],
     values: ['format'],
     positionals: 1,
   },
@@ -606,11 +620,20 @@ function cmdRun(verb: LifecycleVerb): void {
 }
 
 function cmdDoctor(opts: ParsedArgs): void {
-  const ctx = resolveDoctorCtx(path.resolve(opts.positionals[0] ?? '.'));
-  if (opts.flags.check === true && opts.flags.fix === true) {
-    process.stderr.write('vdx doctor: --check reports and --fix writes — pick one\n');
+  const ctx = resolveDoctorCtx(path.resolve(opts.positionals[0] ?? '.'), opts.positionals[0] !== undefined);
+  if ([opts.flags.check, opts.flags.fix, opts.flags.staged].filter((f) => f === true).length > 1) {
+    process.stderr.write('vdx doctor: --check reports, --fix writes, --staged guards a commit — pick one\n');
     process.exit(2);
   }
+  if (opts.flags.staged === true) {
+    const root = resolveProjectRoot(ctx.projectRoot ?? '.') ?? process.cwd();
+    const refusal = runDoctorStaged(root);
+    if (refusal) {
+      process.stderr.write(refusal + '\n');
+      process.exit(1);
+    }
+    return;
+  }
   if (opts.flags.check === true) {
     const text = runDoctorCheck(ctx);
     if (text) process.stdout.write(text + '\n');

package/src/init.ts

@@ -6,7 +6,7 @@ import { at } from './narrow.ts';
 export const STANDARD_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
 export type Verb = (typeof STANDARD_VERBS)[number];
 
-export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.7.0';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v1.8.0';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
   up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],

package/src/memory.ts

@@ -2,8 +2,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { remoteParts } from './author.ts';
-import { claudeConfigDir, projectDirName } from './conversations.ts';
-import { dict, str } from './narrow.ts';
+import { claudeConfigDir, claudeTrusts, projectDirName } from './conversations.ts';
+import { githubToken, machineIo, type HostingIo } from './hosting.ts';
+import { at, dict, errorMessage, list, str } from './narrow.ts';
 
 /**
  * Where Claude Code keeps a project's memory (docs/tasks/claude-memory-in-project).
@@ -17,8 +18,11 @@ import { dict, str } from './narrow.ts';
 export type MemoryState =
   /** In `.claude/memory/`, nothing left in the old place. */
   | { kind: 'inside' }
-  /** In `.claude/memory/`, and notes still lie in the old place — a move made by hand. */
-  | { kind: 'leftovers'; old: string; notes: number; differ: number; onlyOld: number }
+  /**
+   * In `.claude/memory/`, and notes still lie in the old place — a move made by hand. `afterMove`:
+   * vdx set the old place aside before, so a session that started before the move wrote them.
+   */
+  | { kind: 'leftovers'; old: string; notes: number; differ: number; onlyOld: number; afterMove: boolean }
   /** Not set: memory goes to the old place. */
   | { kind: 'outside'; old: string; notes: number }
   /**
@@ -53,6 +57,19 @@ function realRoot(root: string): string {
   }
 }
 
+/**
+ * A folder whose memory vdx may move: not the home directory or above it — its
+ * `.claude/settings.json` is the user's own, read by every project — and not inside
+ * Claude Code's configuration.
+ */
+export function memoryApplies(projectRoot: string, ctx: MemoryCtx): boolean {
+  const root = realRoot(projectRoot);
+  const home = realRoot(ctx.home);
+  const config = realRoot(claudeConfigDir(ctx.env, ctx.home));
+  const within = (a: string, b: string) => a === b || a.startsWith(b + path.sep);
+  return !within(home, root) && !within(root, config);
+}
+
 /** Where the setting is read, in Claude Code's order: local settings, the project's, the user's. */
 function settingFiles(root: string, ctx: MemoryCtx): string[] {
   return [
@@ -95,6 +112,11 @@ function entries(dir: string): string[] {
   }
 }
 
+/** vdx set this place aside once already (`asideName`): what lies there now came after (Sidetrack #5). */
+function setAsideBefore(dir: string): boolean {
+  return entries(path.dirname(dir)).some((n) => n.startsWith(`${path.basename(dir)}.moved-`));
+}
+
 function sameFile(a: string, b: string): boolean {
   try {
     return fs.readFileSync(a).equals(fs.readFileSync(b));
@@ -116,7 +138,14 @@ export function memoryState(projectRoot: string, ctx: MemoryCtx): MemoryState {
       (n) => fs.existsSync(path.join(target, n)) && !sameFile(path.join(old, n), path.join(target, n)),
     );
     const onlyOld = notes.filter((n) => !fs.existsSync(path.join(target, n)));
-    return { kind: 'leftovers', old, notes: notes.length, differ: differ.length, onlyOld: onlyOld.length };
+    return {
+      kind: 'leftovers',
+      old,
+      notes: notes.length,
+      differ: differ.length,
+      onlyOld: onlyOld.length,
+      afterMove: setAsideBefore(old),
+    };
   }
   if (path.basename(setting.dir) === 'memory' && path.basename(path.dirname(setting.dir)) === '.claude') {
     const from = path.dirname(path.dirname(setting.dir));
@@ -145,16 +174,83 @@ function git(root: string, args: string[]): string | null {
   }
 }
 
+/** A host of `git.personal_hosts`: its repos are the owner's alone; `mirrors` — where its repos may be copied. */
+export interface PersonalHost {
+  host: string;
+  /** `github.com/<owner>/{repo}`: a repo of the host may be mirrored there (gitolite's post-update hook). */
+  mirrors: string[];
+}
+
+/** The profile's `git.personal_hosts`: a host name, or `{host, mirrors}`. */
+export function personalHosts(
+  listed: Array<string | { host: string; mirrors?: string[] }> | undefined,
+): PersonalHost[] {
+  return (listed ?? []).map((h) =>
+    typeof h === 'string'
+      ? { host: h.toLowerCase(), mirrors: [] }
+      : { host: h.host.toLowerCase(), mirrors: h.mirrors ?? [] },
+  );
+}
+
+/** Who may read where the repo's commits go: only its owner, or — why not. */
+export type Readers = { only: true } | { only: false; why: string };
+
 /**
- * A personal project's memory goes under git with it; anyone else's would reach
- * whoever clones it (DL #3, #4). Personal: no origin, or origin on a host the
- * profile names in `git.personal_hosts`.
+ * Whether only the owner reads every place a commit of this repo reaches (DL #12 of
+ * docs/tasks/claude-memory-in-project): origin on a host the profile names as the
+ * owner's (`git.personal_hosts`), or a private GitHub repo with no other collaborator;
+ * and every mirror the profile names for that host — absent, or private and nobody
+ * else's. No origin: nothing leaves the machine. GitHub is asked with the token gh
+ * keeps; no token, no answer, `VDX_OFFLINE` — not known, so not only.
  */
-export function isPersonalProject(projectRoot: string, personalHosts: string[]): boolean {
-  const url = git(projectRoot, ['remote', 'get-url', 'origin']);
-  if (!url) return true;
-  const host = remoteParts(url).host.toLowerCase();
-  return personalHosts.some((h) => h.toLowerCase() === host);
+export function memoryReaders(io: HostingIo, hosts: PersonalHost[]): Readers {
+  const url = io.git(['remote', 'get-url', 'origin']);
+  if (!url) return { only: true };
+  const { host, path: repo } = remoteParts(url);
+  const lower = host.toLowerCase();
+  const own = hosts.find((h) => h.host === lower);
+  const places: string[] = [];
+  if (lower === 'github.com') places.push(repo);
+  else if (!own)
+    return { only: false, why: `origin is on ${host} — not a host the profile names as yours (git.personal_hosts)` };
+  for (const m of own?.mirrors ?? []) {
+    const at = m.replace(/^https?:\/\//, '').replace('{repo}', repo);
+    if (!at.startsWith('github.com/'))
+      return { only: false, why: `the mirror ${m} is not on GitHub — vdx cannot tell who reads it` };
+    places.push(at.slice('github.com/'.length));
+  }
+  if (places.length === 0) return { only: true };
+  if (io.env.VDX_OFFLINE) return { only: false, why: 'VDX_OFFLINE is set — GitHub was not asked who reads' };
+  const token = githubToken(io)?.token ?? null;
+  if (!token) return { only: false, why: 'no GitHub token to ask who reads — gh auth login' };
+  try {
+    const me = str(at(io.get('/user', token).body, 'login'));
+    if (!me) return { only: false, why: 'GitHub named no user for the token' };
+    for (const p of places) {
+      const r = io.get(`/repos/${p}`, token);
+      if (r.status === 404 && p !== repo) continue; // that mirror does not exist
+      if (r.status !== 200) return { only: false, why: `GitHub answered ${r.status} for ${p}` };
+      if (at(r.body, 'private') !== true) return { only: false, why: `github.com/${p} is public` };
+      const c = io.get(`/repos/${p}/collaborators?per_page=100`, token);
+      if (c.status !== 200) return { only: false, why: `GitHub does not show who reads github.com/${p} (${c.status})` };
+      const others = list(c.body)
+        .map((x) => str(at(x, 'login')))
+        .filter((l) => l && l !== me);
+      if (others.length) return { only: false, why: `github.com/${p} is read by ${others.length} more besides ${me}` };
+    }
+    return { only: true };
+  } catch (e) {
+    return { only: false, why: `GitHub did not answer: ${errorMessage(e)}` };
+  }
+}
+
+/** A personal project: its memory may go under git (DL #3, #4, #12). */
+export function isPersonalProject(
+  projectRoot: string,
+  hosts: PersonalHost[],
+  io: HostingIo = machineIo(projectRoot),
+): boolean {
+  return memoryReaders(io, hosts).only;
 }
 
 /** Needs `vdx doctor --fix`: anything but inside, or a path of the owner's own. */
@@ -172,6 +268,8 @@ export function describeMemory(state: MemoryState, ctx: MemoryCtx): string {
     case 'inside':
       return 'in .claude/memory/';
     case 'leftovers': {
+      if (state.afterMove)
+        return `in .claude/memory/, and ${state.notes} note(s) written in the old place after the move, ${tilde(state.old, ctx.home)} — by a session that started before it; the fix brings them in`;
       const parts = [state.differ ? `${state.differ} differ` : '', state.onlyOld ? `${state.onlyOld} only there` : '']
         .filter(Boolean)
         .join(', ');
@@ -207,10 +305,10 @@ function asideName(dir: string, today: string): string {
   return name;
 }
 
-/** Copies what `to` lacks; a name `to` already has stays as it is there. Returns the names kept. */
-function copyMissing(from: string, to: string): { copied: number; kept: string[] } {
+/** Copies what `to` lacks; a name `to` already has stays as it is there. Returns the names copied and kept. */
+function copyMissing(from: string, to: string): { copied: string[]; kept: string[] } {
   fs.mkdirSync(to, { recursive: true });
-  let copied = 0;
+  const copied: string[] = [];
   const kept: string[] = [];
   for (const name of entries(from)) {
     const src = path.join(from, name);
@@ -220,11 +318,42 @@ function copyMissing(from: string, to: string): { copied: number; kept: string[]
       continue;
     }
     fs.cpSync(src, dst, { recursive: true, errorOnExist: true, force: false });
-    copied++;
+    copied.push(name);
   }
   return { copied, kept };
 }
 
+const INDEX = 'MEMORY.md';
+
+/**
+ * Notes a session wrote at the old place after the move, brought into `to`: the agent finds a
+ * note by its line in MEMORY.md, so the lines of the old index that point at the notes
+ * brought in join `to`'s — those alone. A line about a note `to` already has is the
+ * project's agent's to judge (DL #8). Returns what was done, one line each, and the names kept.
+ */
+function bringIn(from: string, to: string, what: string, aside: string): { done: string[]; differ: string[] } {
+  const { copied, kept } = copyMissing(from, to);
+  const done = [`${copied.length} note(s) ${what} → .claude/memory/`];
+  const notes = copied.filter((n) => n !== INDEX);
+  const src = path.join(from, INDEX);
+  const dst = path.join(to, INDEX);
+  if (notes.length && !copied.includes(INDEX) && fs.existsSync(src)) {
+    const have = fs.existsSync(dst) ? fs.readFileSync(dst, 'utf8') : '';
+    const lines = fs
+      .readFileSync(src, 'utf8')
+      .split('\n')
+      .filter((l) => notes.some((n) => l.includes(`](${n})`) && !have.includes(`(${n})`)));
+    if (lines.length) {
+      fs.writeFileSync(dst, have + (have && !have.endsWith('\n') ? '\n' : '') + lines.join('\n') + '\n');
+      done.push(`${lines.length} line(s) of its MEMORY.md → .claude/memory/MEMORY.md, for the notes brought in`);
+    }
+  }
+  const differ = kept.filter((n) => n !== INDEX);
+  if (differ.length)
+    done.push(`kept .claude/memory/ as it is for ${differ.join(', ')} — the later copy differs, it stays in ${aside}`);
+  return { done, differ };
+}
+
 /** Sets `autoMemoryDirectory` in a settings file, keeping its other keys. */
 function writeSetting(file: string, dir: string): void {
   let doc: Record<string, unknown> = {};
@@ -283,6 +412,8 @@ function moveConversations(from: string, to: string, today: string): string {
  * already has stays, the old place is renamed. Returns what was done, one line each.
  */
 export function fixMemory(projectRoot: string, state: MemoryState, ctx: MemoryCtx, opts: MemoryFixOptions): string[] {
+  if (!memoryApplies(projectRoot, ctx))
+    throw new Error(`${projectRoot} is no project folder — its settings are the user's own`);
   const root = realRoot(projectRoot);
   const target = path.join(root, MEMORY);
   const done: string[] = [];
@@ -297,12 +428,22 @@ export function fixMemory(projectRoot: string, state: MemoryState, ctx: MemoryCt
     case 'custom':
       return done;
     case 'leftovers':
+      // Written after vdx's move by a session that started before it: newer than anything inside.
+      if (state.afterMove)
+        done.push(
+          ...bringIn(
+            state.old,
+            target,
+            'written in the old place after the move',
+            tilde(asideName(state.old, opts.today), ctx.home),
+          ).done,
+        );
       setAside(state.old);
       return done;
     case 'outside': {
-      const { copied, kept } = fs.existsSync(state.old) ? copyMissing(state.old, target) : { copied: 0, kept: [] };
+      const { copied, kept } = fs.existsSync(state.old) ? copyMissing(state.old, target) : { copied: [], kept: [] };
       if (!fs.existsSync(target)) fs.mkdirSync(target, { recursive: true });
-      done.push(`${copied} note(s) → .claude/memory/`);
+      done.push(`${copied.length} note(s) → .claude/memory/`);
       if (kept.length) done.push(`kept .claude/memory/ as it is for ${kept.join(', ')} — the old copy differs`);
       const file = path.join(root, '.claude', opts.personal ? 'settings.json' : 'settings.local.json');
       writeSetting(file, target);
@@ -310,24 +451,52 @@ export function fixMemory(projectRoot: string, state: MemoryState, ctx: MemoryCt
       if (!opts.personal && !opts.underGit && excludeMemory(root)) done.push('.claude/memory/ → .git/info/exclude');
       setAside(state.old);
       if (opts.personal && git(root, ['rev-parse', '--git-dir']) !== null) {
-        done.push('commit .claude/memory/ and .claude/settings.json with the project');
+        // The project's own .gitignore may keep .claude/ out (mediko, 2026-10-23).
+        const ignored = git(root, ['check-ignore', '-q', '.claude/memory/MEMORY.md']) !== null;
+        done.push(
+          ignored
+            ? ".claude/memory/ stays out of git by the project's own .gitignore"
+            : 'commit .claude/memory/ and .claude/settings.json with the project',
+        );
       }
       return done;
     }
     case 'moved':
     case 'elsewhere': {
-      writeSetting(state.setting.file, target);
-      done.push(`autoMemoryDirectory → ${target}/ (${path.relative(root, state.setting.file)})`);
+      // The path is rewritten where it was read — unless that file is the user's, read by every
+      // project, or another clone's path in the repo's shared settings.json: then this clone's
+      // own local settings, read first (Sidetrack #4).
+      const local = path.join(root, '.claude', 'settings.local.json');
+      const inProject = path.dirname(state.setting.file) === path.join(root, '.claude');
+      const shared =
+        state.kind === 'elsewhere' &&
+        state.setting.file !== local &&
+        git(root, ['ls-files', '--error-unmatch', '--', path.relative(root, state.setting.file)]) !== null;
+      const file = inProject && !shared ? state.setting.file : local;
+      writeSetting(file, target);
+      done.push(`autoMemoryDirectory → ${target}/ (${path.relative(root, file)})`);
+      if (shared) done.push(`${path.relative(root, state.setting.file)} keeps the other clone's path — it is shared`);
       if (state.kind === 'moved' && state.stray) {
-        const { copied, kept } = copyMissing(state.stray, target);
+        const brought = bringIn(
+          state.stray,
+          target,
+          'written at the old path after the move',
+          tilde(state.stray, ctx.home),
+        );
         done.push(
-          `${copied} note(s) written at the old path after the move → .claude/memory/${kept.length ? `; kept .claude/memory/ as it is for ${kept.join(', ')}` : ''} — ${tilde(state.from, ctx.home)} holds only them, remove it`,
+          ...brought.done,
+          `${tilde(state.from, ctx.home)} holds only them — remove it${brought.differ.length ? ` once ${brought.differ.join(', ')} is settled` : ''}`,
         );
       }
       if (state.kind === 'moved' && state.conversations) {
         const here = path.join(claudeConfigDir(ctx.env, ctx.home), 'projects', projectDirName(root));
         done.push(moveConversations(state.conversations, here, opts.today));
       }
+      // Claude Code trusts a folder by its path: the moved one is new to it (Sidetrack #2).
+      if (state.kind === 'moved' && claudeTrusts(root, ctx.env, ctx.home) === false)
+        done.push(
+          'Claude Code has not trusted this folder yet: its first start here stops on the trust window — start vdx ai here once and answer it; a detached start (the mail session) is refused until then',
+        );
       return done;
     }
   }
@@ -339,7 +508,9 @@ export interface ProjectMemoryDeps {
   log: (line: string) => void;
   today: string;
   /** The profile's `git.personal_hosts`. */
-  personalHosts: string[];
+  personalHosts: PersonalHost[];
+  /** Asks GitHub who reads the repo; the machine's own by default. */
+  io?: HostingIo;
 }
 
 /**
@@ -353,14 +524,17 @@ export function fixProjectMemory(
   ctx: MemoryCtx,
   deps: ProjectMemoryDeps,
 ): string[] {
-  const personal = isPersonalProject(projectRoot, deps.personalHosts);
+  const personal = isPersonalProject(projectRoot, deps.personalHosts, deps.io);
   let underGit = false;
   if (state.kind === 'outside' && !personal && git(projectRoot, ['rev-parse', '--git-dir']) !== null) {
     deps.log(`  ${path.basename(projectRoot)} is not a personal repo: memory under git reaches whoever clones it`);
     underGit = /^y(es)?$/i.test(deps.ask('  Keep .claude/memory/ under git? [y/N] ')?.trim() ?? '');
   }
   const done = fixMemory(projectRoot, state, ctx, { personal, underGit, today: deps.today });
-  if (done.length && (state.kind === 'outside' || state.kind === 'moved')) {
+  if (
+    done.length &&
+    (state.kind === 'outside' || state.kind === 'moved' || (state.kind === 'leftovers' && state.afterMove))
+  ) {
     done.push('sessions of this project running now keep the old place until they restart');
   }
   return done;