ccprofiles-core 0.10.3 → 0.12.0

package/dist/adopt.js

@@ -82,6 +82,7 @@ export async function preserveSecretRefs(newM, oldM, getSecret) {
         if (!old)
             continue;
         pr.skipPermissions = old.skipPermissions;
+        pr.fallback = old.fallback;
         // buildManifest derives `cl-<dirname>`, which silently renames a hand-picked alias
         // (cl-plb -> cl-data-plb) and makes the next apply rewrite the user's rc block.
         pr.launcher = old.launcher;

package/dist/apply.js

@@ -116,7 +116,9 @@ export function planApply(m, live, p, resolvedSettingsEnv, sharedRoot = join(p.h
                 actions.push({ kind: 'unshare-session-dir', from, to });
         }
         const senv = pr.settingsEnv ?? {}; // literals in older tests may omit the field
-        if (agent === 'claude' && Object.keys(senv).length > 0) {
+        // No length guard: an empty settingsEnv is a declaration ("no env"), so it must still clear
+        // whatever is live — otherwise `provider anthropic --login` leaves the old token in place.
+        if (agent === 'claude') {
             let desired = resolvedSettingsEnv?.[pr.name];
             if (!desired) {
                 if (Object.values(senv).some(v => v.startsWith(SECRET_PREFIX)))
@@ -124,7 +126,10 @@ export function planApply(m, live, p, resolvedSettingsEnv, sharedRoot = join(p.h
                 desired = senv;
             }
             const currentEnv = lp?.settingsEnv ?? null;
-            if (!currentEnv || JSON.stringify(sortKeys(currentEnv)) !== JSON.stringify(sortKeys(desired))) {
+            const drift = currentEnv
+                ? JSON.stringify(sortKeys(currentEnv)) !== JSON.stringify(sortKeys(desired))
+                : Object.keys(desired).length > 0; // no live dir yet: don't create settings.json just to write {}
+            if (drift) {
                 actions.push({ kind: 'set-settings-env', settingsPath: join(dir, 'settings.json'), env: desired });
             }
         }

package/dist/manifest.d.ts

@@ -1,6 +1,13 @@
 import { z } from 'zod';
 export declare class ManifestError extends Error {
 }
+/** Bundled status line used when a Claude profile has no existing statusLine setting. */
+export declare const DEFAULT_STATUS_LINE: {
+    readonly type: "command";
+    readonly command: "clp statusline";
+    readonly padding: 0;
+    readonly refreshInterval: 10;
+};
 declare const McpServerSchema: z.ZodEffects<z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
     args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -44,6 +51,7 @@ declare const ProfileSchema: z.ZodObject<{
     settingsEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     skipPermissions: z.ZodDefault<z.ZodBoolean>;
     sharedSessions: z.ZodDefault<z.ZodBoolean>;
+    fallback: z.ZodOptional<z.ZodString>;
     plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     env: Record<string, string>;
@@ -58,6 +66,7 @@ declare const ProfileSchema: z.ZodObject<{
     sharedSessions: boolean;
     plugins: string[];
     agent?: "claude" | "codex" | undefined;
+    fallback?: string | undefined;
 }, {
     name: string;
     dir: string;
@@ -70,6 +79,7 @@ declare const ProfileSchema: z.ZodObject<{
     settingsEnv?: Record<string, string> | undefined;
     skipPermissions?: boolean | undefined;
     sharedSessions?: boolean | undefined;
+    fallback?: string | undefined;
     plugins?: string[] | undefined;
 }>;
 declare const MarketplaceSchema: z.ZodObject<{
@@ -94,6 +104,7 @@ declare const ManifestSchema: z.ZodObject<{
         settingsEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
         skipPermissions: z.ZodDefault<z.ZodBoolean>;
         sharedSessions: z.ZodDefault<z.ZodBoolean>;
+        fallback: z.ZodOptional<z.ZodString>;
         plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         env: Record<string, string>;
@@ -108,6 +119,7 @@ declare const ManifestSchema: z.ZodObject<{
         sharedSessions: boolean;
         plugins: string[];
         agent?: "claude" | "codex" | undefined;
+        fallback?: string | undefined;
     }, {
         name: string;
         dir: string;
@@ -120,6 +132,7 @@ declare const ManifestSchema: z.ZodObject<{
         settingsEnv?: Record<string, string> | undefined;
         skipPermissions?: boolean | undefined;
         sharedSessions?: boolean | undefined;
+        fallback?: string | undefined;
         plugins?: string[] | undefined;
     }>, "many">;
     mcpServers: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
@@ -181,6 +194,7 @@ declare const ManifestSchema: z.ZodObject<{
         sharedSessions: boolean;
         plugins: string[];
         agent?: "claude" | "codex" | undefined;
+        fallback?: string | undefined;
     }[];
     mcpServers: Record<string, z.objectOutputType<{
         command: z.ZodOptional<z.ZodString>;
@@ -208,6 +222,7 @@ declare const ManifestSchema: z.ZodObject<{
         settingsEnv?: Record<string, string> | undefined;
         skipPermissions?: boolean | undefined;
         sharedSessions?: boolean | undefined;
+        fallback?: string | undefined;
         plugins?: string[] | undefined;
     }[];
     mcpServers: Record<string, z.objectInputType<{
@@ -226,6 +241,7 @@ export type McpServerDef = z.infer<typeof McpServerSchema>;
 export type ProfileDecl = z.infer<typeof ProfileSchema>;
 export type Manifest = z.infer<typeof ManifestSchema>;
 export type MarketplaceDef = z.infer<typeof MarketplaceSchema>;
+export declare const SAFE_NAME: RegExp;
 /**
  * True if `yaml` (raw manifest.yaml text, or any string) contains a plaintext provider
  * token. saveManifest() uses this to decide whether to skip the git commit; doctor checks

package/dist/manifest.js

@@ -8,6 +8,10 @@ import { atomicWrite } from './fsutil.js';
 const exec = promisify(execFile);
 export class ManifestError extends Error {
 }
+/** Bundled status line used when a Claude profile has no existing statusLine setting. */
+export const DEFAULT_STATUS_LINE = {
+    type: 'command', command: 'clp statusline', padding: 0, refreshInterval: 10,
+};
 const McpServerSchema = z.object({
     command: z.string().optional(),
     args: z.array(z.string()).optional(),
@@ -27,6 +31,7 @@ const ProfileSchema = z.object({
     settingsEnv: z.record(z.string()).default({}),
     skipPermissions: z.boolean().default(false),
     sharedSessions: z.boolean().default(false),
+    fallback: z.string().optional(),
     plugins: z.array(z.string()).default([]),
 });
 const MarketplaceSchema = z.object({ source: z.string().min(1) });
@@ -45,7 +50,9 @@ const ManifestSchema = z.object({
 // identifiers that get interpolated into shell launcher code must be injection-safe
 // leading '-' is forbidden (but internal '-' still allowed) so a value can never be parsed as a
 // CLI flag when passed as a positional argv entry (e.g. `claude plugin install <id>`)
-const SAFE_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/; // profile names, launcher names, secret refs
+// exported: SecretsStore.set() rejects names this forbids, so a secret can never be stored under
+// a name no manifest could ever reference (the failure used to surface only at attach time)
+export const SAFE_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/; // profile names, launcher names, secret refs
 const SAFE_ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/; // POSIX/PowerShell env var names
 const SAFE_LINK_ENTRY = /^[A-Za-z0-9._-]+$/; // one profile-dir child; never a path
 const SAFE_SOURCE = /^[A-Za-z0-9._@:/][A-Za-z0-9._/@:-]*$/; // marketplace source (interpolated into `claude plugin` shell-out); no leading '-'
@@ -74,6 +81,8 @@ export function assertSafeManifest(m) {
     for (const p of m.profiles) {
         if (!SAFE_NAME.test(p.name))
             throw new ManifestError(`unsafe profile name: ${JSON.stringify(p.name)} (allowed: letters, digits, - _)`);
+        if (p.fallback !== undefined && !SAFE_NAME.test(p.fallback))
+            throw new ManifestError(`unsafe fallback profile in profile "${p.name}": ${JSON.stringify(p.fallback)}`);
         if (p.launcher !== null && !SAFE_NAME.test(p.launcher))
             throw new ManifestError(`unsafe launcher name in profile "${p.name}": ${JSON.stringify(p.launcher)}`);
         if (SHELL_META.test(p.dir))
@@ -133,6 +142,12 @@ export function parseManifest(text) {
         for (const name of p.mcp)
             if (!m.mcpServers[name])
                 throw new ManifestError(`profile "${p.name}" references undefined mcp server "${name}"`);
+    for (const p of m.profiles)
+        if (p.fallback !== undefined) {
+            const target = m.profiles.find(q => q.name === p.fallback);
+            if (!target || (target.agent ?? 'claude') !== 'claude' || (p.agent ?? 'claude') !== 'claude' || target.name === p.name)
+                throw new ManifestError(`profile "${p.name}" has invalid Claude fallback "${p.fallback}"`);
+        }
     for (const p of m.profiles)
         for (const id of p.plugins) {
             const at = id.lastIndexOf('@');
@@ -181,7 +196,9 @@ export async function saveManifest(root, m) {
 /** True for the two git outcomes saveManifest treats as expected/benign, not a real failure. */
 function isBenignGitError(e) {
     const text = gitErrorMessage(e);
-    return /nothing to commit/i.test(text) || /not a git repository/i.test(text);
+    // "no changes added to commit" is git's wording when the only dirty paths are ones `add -A`
+    // cannot stage (nested repos) — still nothing for us to commit.
+    return /nothing to commit/i.test(text) || /no changes added to commit/i.test(text) || /not a git repository/i.test(text);
 }
 function gitErrorMessage(e) {
     const err = e;

package/dist/plugins.d.ts

@@ -1,5 +1,8 @@
 export interface PluginRunner {
     marketplaceAdd(configDir: string, source: string): Promise<void>;
+    /** `claude plugin marketplace update` — refetch the marketplace so "latest" is actually latest.
+     *  Without this, `update` is a silent no-op in any profile whose marketplace clone is stale. */
+    marketplaceUpdate(configDir: string, name: string): Promise<void>;
     install(configDir: string, id: string): Promise<void>;
     uninstall(configDir: string, id: string): Promise<void>;
     /** `claude plugin update` — moves a plugin to the marketplace's latest. There is deliberately no
@@ -76,3 +79,23 @@ export declare function claudeMemCacheDirs(configDir: string): Promise<string[]>
 export declare function pruneStaleVersionDirs(cacheDir: string): Promise<string[]>;
 /** If a profile's plugins/ is a legacy symlink into the old shared pool, restore it to a real dir. */
 export declare function restoreLegacyPluginSymlink(pluginsDir: string): Promise<boolean>;
+/**
+ * Repair installed_plugins.json entries whose installPath no longer exists on disk.
+ *
+ * This is the other half of pruneStaleVersionDirs. Pruning removes superseded cache dirs but leaves
+ * the bookkeeping untouched, and installed_plugins.json holds one entry PER SCOPE — a `user` entry
+ * plus a `project` entry for every directory Claude was ever launched from. `claude plugin update`
+ * only moves the user-scope pin, so the project-scope entries stay on an old version, and the next
+ * prune deletes the dir underneath them. Claude Code then refuses to load their hooks outright:
+ * "Plugin directory does not exist: .../claude-mem/13.16.1 — run /plugin to reinstall", on every
+ * Stop hook, forever. Six of eight profiles were in that state on 2026-08-30.
+ *
+ * Re-point rather than drop where a sibling version dir survived: the surviving dir is the one
+ * prune kept, i.e. the latest, which is exactly where `claude plugin update` would have moved the
+ * entry anyway — so the repair converges scopes onto one version instead of disabling the plugin.
+ * Only numeric version dirs qualify; a versionless plugin's sha/"unknown" siblings are unrelated
+ * builds, so those entries are dropped and left for `plugins apply` to reinstall.
+ */
+export declare function repairInstalledPlugins(configDir: string, opts?: {
+    dryRun?: boolean;
+}): Promise<string[]>;

package/dist/plugins.js

@@ -1,6 +1,7 @@
-import { cp, lstat, mkdir, readdir, readlink, rm, unlink } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { cp, lstat, mkdir, readdir, readFile, readlink, rm, unlink } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { atomicWrite } from './fsutil.js';
 export function marketplaceOf(id) {
     const at = id.lastIndexOf('@');
     return at > 0 ? id.slice(at + 1) : null;
@@ -67,6 +68,18 @@ export async function reconcileProfilePlugins(opts) {
         await opts.runner.install(opts.configDir, id);
         log.push(`install ${id}`);
     }
+    // `claude plugin update` moves to the marketplace clone's latest, and that clone is per-profile
+    // and only refreshed on demand. A profile whose clone is months old therefore "updates" to the
+    // version it already has, and cross-profile drift never converges — refetch first.
+    const refreshed = new Set();
+    for (const id of update) {
+        const mkt = marketplaceOf(id);
+        if (mkt && !refreshed.has(mkt)) {
+            await opts.runner.marketplaceUpdate(opts.configDir, mkt);
+            refreshed.add(mkt);
+            log.push(`marketplace update ${mkt}`);
+        }
+    }
     for (const id of update) {
         await opts.runner.update(opts.configDir, id);
         log.push(`update ${id}`);
@@ -166,3 +179,75 @@ export async function restoreLegacyPluginSymlink(pluginsDir) {
     await cp(target, pluginsDir, { recursive: true, force: false, errorOnExist: false });
     return true;
 }
+/** Highest-semver cache dir that still exists beside a missing one, or null if none survived. */
+function survivingVersionDir(missingPath) {
+    const parent = dirname(missingPath);
+    let names;
+    try {
+        names = readdirSync(parent);
+    }
+    catch {
+        return null;
+    }
+    const versions = names.filter(n => /^\d/.test(n) && existsSync(join(parent, n))).sort(compareVersionDir);
+    return versions.length ? join(parent, versions[versions.length - 1]) : null;
+}
+/**
+ * Repair installed_plugins.json entries whose installPath no longer exists on disk.
+ *
+ * This is the other half of pruneStaleVersionDirs. Pruning removes superseded cache dirs but leaves
+ * the bookkeeping untouched, and installed_plugins.json holds one entry PER SCOPE — a `user` entry
+ * plus a `project` entry for every directory Claude was ever launched from. `claude plugin update`
+ * only moves the user-scope pin, so the project-scope entries stay on an old version, and the next
+ * prune deletes the dir underneath them. Claude Code then refuses to load their hooks outright:
+ * "Plugin directory does not exist: .../claude-mem/13.16.1 — run /plugin to reinstall", on every
+ * Stop hook, forever. Six of eight profiles were in that state on 2026-08-30.
+ *
+ * Re-point rather than drop where a sibling version dir survived: the surviving dir is the one
+ * prune kept, i.e. the latest, which is exactly where `claude plugin update` would have moved the
+ * entry anyway — so the repair converges scopes onto one version instead of disabling the plugin.
+ * Only numeric version dirs qualify; a versionless plugin's sha/"unknown" siblings are unrelated
+ * builds, so those entries are dropped and left for `plugins apply` to reinstall.
+ */
+export async function repairInstalledPlugins(configDir, opts = {}) {
+    const file = join(configDir, 'plugins', 'installed_plugins.json');
+    let doc;
+    // A corrupt file must not be rewritten from a half-parse — bail and leave it for a human.
+    try {
+        doc = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    if (!doc?.plugins || typeof doc.plugins !== 'object')
+        return [];
+    const log = [];
+    for (const [id, entries] of Object.entries(doc.plugins)) {
+        if (!Array.isArray(entries))
+            continue;
+        const kept = [];
+        for (const e of entries) {
+            const path = e?.installPath;
+            if (typeof path !== 'string' || existsSync(path)) {
+                kept.push(e);
+                continue;
+            }
+            const scope = e.scope ?? '?';
+            const survivor = survivingVersionDir(path);
+            if (survivor) {
+                kept.push({ ...e, installPath: survivor, version: basename(survivor) });
+                log.push(`${id} (${scope}): ${e.version} → ${basename(survivor)} — cache dir was pruned`);
+            }
+            else {
+                log.push(`${id} (${scope}): dropped — ${path} is gone and no version survived`);
+            }
+        }
+        if (kept.length)
+            doc.plugins[id] = kept;
+        else
+            delete doc.plugins[id];
+    }
+    if (log.length && !opts.dryRun)
+        await atomicWrite(file, JSON.stringify(doc, null, 2) + '\n');
+    return log;
+}

package/dist/rcblock.js

@@ -28,7 +28,10 @@ function renderPosix(pr, p) {
     const flag = pr.skipPermissions ? codex ? ' --dangerously-bypass-approvals-and-sandbox' : ' --dangerously-skip-permissions' : '';
     const home = codex ? 'CODEX_HOME' : 'CLAUDE_CONFIG_DIR';
     const command = codex ? 'codex' : 'claude';
-    lines.push(`  ${home}="${profileDirExpr(pr, p)}" ${command}${flag} "$@"`, '}');
+    if (!codex && pr.fallback)
+        lines.push(`  command ccprofiles fallback run --from ${pr.name} -- "$@"`, '}');
+    else
+        lines.push(`  ${home}="${profileDirExpr(pr, p)}" ${command}${flag} "$@"`, '}');
     return lines.join('\n');
 }
 function renderPwsh(pr, p) {
@@ -43,7 +46,10 @@ function renderPwsh(pr, p) {
     const flag = pr.skipPermissions ? codex ? ' --dangerously-bypass-approvals-and-sandbox' : ' --dangerously-skip-permissions' : '';
     const home = codex ? 'CODEX_HOME' : 'CLAUDE_CONFIG_DIR';
     const command = codex ? 'codex' : 'claude';
-    lines.push(`  $env:${home} = "${profileDirExpr(pr, p)}"`, `  ${command}${flag} @args`, '}');
+    if (!codex && pr.fallback)
+        lines.push(`  ccprofiles fallback run --from ${pr.name} -- @args`, '}');
+    else
+        lines.push(`  $env:${home} = "${profileDirExpr(pr, p)}"`, `  ${command}${flag} @args`, '}');
     return lines.join('\n');
 }
 export function renderRcBlock(m, p) {

package/dist/secrets.js

@@ -4,6 +4,7 @@ import { existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { atomicWrite } from './fsutil.js';
+import { SAFE_NAME } from './manifest.js';
 export class FileBackend {
     filePath;
     passphrase;
@@ -176,6 +177,8 @@ export class SecretsStore {
     get backendName() { return this.backend.name; }
     async get(key) { return this.backend.get(key); }
     async set(key, value) {
+        if (!SAFE_NAME.test(key))
+            throw new Error(`unsafe secret name: ${JSON.stringify(key)} (allowed: letters, digits, - _; must not start with -)`);
         await this.backend.set(key, value);
         await this.writeIndex([...(await this.readIndex()), key]);
     }

package/dist/sessions.d.ts

@@ -1,7 +1,12 @@
 export interface SessionMeta {
     id: string;
     mtime: number;
+    /** Timestamp (ms) of the last user/assistant record — when you last chatted, not when the
+     *  file was created or last copied. Falls back to mtime when no record carries a timestamp. */
+    lastActivity: number;
     messageCount: number;
+    /** Session name: your `/rename` title if set, else Claude's auto-generated one. */
+    title?: string | null;
     firstPrompt: string | null;
     gitBranch: string | null;
     model: string | null;
@@ -9,6 +14,8 @@ export interface SessionMeta {
     /** true when the transcript was too large to fully scan (per-file cap) or the per-request
      *  byte budget ran out before reaching it — metadata is best-effort / incomplete. */
     truncated?: boolean;
+    /** Driven by the Agent SDK (e.g. a plugin's background worker), not a chat you'd resume. */
+    automated?: boolean;
 }
 export interface ProjectSessions {
     agent: 'claude' | 'codex';
@@ -48,6 +55,13 @@ export declare function decodeProjectDir(name: string): string;
  * simply fails JSON.parse and is skipped — no need to guess which line is incomplete.
  */
 export declare function headCwd(head: string, pick: (rec: any) => string | undefined): string | null;
+/**
+ * Latest chat-record timestamp in a JSONL slice, or null. Partial lines at either edge of a
+ * slice fail JSON.parse and are skipped.
+ */
+export declare function lastChatTime(text: string): number | null;
+/** Latest custom title in a Claude JSONL slice, else the latest AI-generated one, else null. */
+export declare function sessionTitle(text: string): string | null;
 export declare function scanSessions(opts: {
     sharedRoot: string;
     profiles: {
@@ -56,6 +70,32 @@ export declare function scanSessions(opts: {
         agent?: 'claude' | 'codex';
     }[];
 }): Promise<ProjectSessions[]>;
+export interface RecentSession {
+    agent: 'claude' | 'codex';
+    scope: string;
+    project: string;
+    session: SessionMeta;
+}
+/** The `limit` sessions you chatted in most recently, across every project and profile. */
+export declare function recentSessions(rows: ProjectSessions[], limit?: number): RecentSession[];
+/**
+ * Paste-ready command that reopens a session in its own project under the profile that owns it.
+ * Prefers the profile's launcher (it carries provider env and secrets); otherwise points the
+ * agent at the profile dir directly. `owner` is null when no declared profile matches the scope.
+ */
+export declare function resumeCommand(r: Pick<RecentSession, 'agent' | 'project' | 'session'>, owner: {
+    launcher: string | null;
+    dir: string;
+} | null): string;
+/**
+ * Which profile reopens a session: the one named by its scope, or — for the shared pool — the
+ * first profile of the same agent that shares sessions.
+ */
+export declare function sessionOwner<P extends {
+    name: string;
+    agent?: 'claude' | 'codex';
+    sharedSessions?: boolean;
+}>(r: Pick<RecentSession, 'agent' | 'scope'>, profiles: P[]): P | null;
 /** Read visible conversation and tool activity for one known managed session. */
 export declare function readSessionTranscript(opts: {
     sharedRoot: string;

package/dist/sessions.js

@@ -7,8 +7,9 @@ const claudeSessionCache = new Map();
 const codexSessionCache = new Map();
 /** Per-file cap: a transcript above this size is summarized without reading its content. */
 const MAX_FILE_SCAN_BYTES = 10 * 1024 * 1024;
-// enough to reach the first record carrying cwd, without reading a multi-MB transcript
-const HEAD_SCAN_BYTES = 64 * 1024;
+// enough to reach the first real prompt (Codex Desktop front-loads ~140KB of AGENTS.md and
+// instructions), without reading a multi-MB transcript
+const HEAD_SCAN_BYTES = 256 * 1024;
 /** Per-request cap: once this many bytes have been read from disk in one scanSessions() call,
  *  remaining (uncached) files are summarized without reading their content either. */
 const MAX_TOTAL_SCAN_BYTES = 50 * 1024 * 1024;
@@ -28,13 +29,15 @@ export function sessionScanCacheStats() {
 export function decodeProjectDir(name) {
     return name.replace(/^-/, '/').replace(/-/g, '/');
 }
-/** First `bytes` of a file, for cheap field recovery without reading a multi-MB transcript. */
-async function readHead(file, bytes = HEAD_SCAN_BYTES) {
+/** First (or, with `fromEnd`, last) `bytes` of a file, for cheap field recovery without
+ *  reading a multi-MB transcript. */
+async function readHead(file, bytes = HEAD_SCAN_BYTES, fromEnd = false) {
     let fh = null;
     try {
         fh = await open(file, 'r');
         const buf = Buffer.alloc(bytes);
-        const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+        const pos = fromEnd ? Math.max(0, (await fh.stat()).size - bytes) : 0;
+        const { bytesRead } = await fh.read(buf, 0, bytes, pos);
         return buf.subarray(0, bytesRead).toString('utf8');
     }
     catch {
@@ -65,14 +68,76 @@ export function headCwd(head, pick) {
     }
     return null;
 }
+/** Is this record a chat turn (user or assistant), in either the Claude or Codex format? */
+function isChatRecord(rec) {
+    if (rec?.type === 'user' || rec?.type === 'assistant')
+        return true;
+    const p = rec?.payload;
+    if (rec?.type === 'response_item')
+        return p?.type === 'message' && (p.role === 'user' || p.role === 'assistant');
+    return rec?.type === 'event_msg' && (p?.type === 'user_message' || p?.type === 'agent_message');
+}
+/**
+ * Latest chat-record timestamp in a JSONL slice, or null. Partial lines at either edge of a
+ * slice fail JSON.parse and are skipped.
+ */
+export function lastChatTime(text) {
+    let last = null;
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isChatRecord(rec) || typeof rec.timestamp !== 'string')
+            continue;
+        const t = Date.parse(rec.timestamp);
+        if (!Number.isNaN(t) && (last === null || t > last))
+            last = t;
+    }
+    return last;
+}
+/** Latest custom title in a Claude JSONL slice, else the latest AI-generated one, else null. */
+export function sessionTitle(text) {
+    let custom = null, ai = null;
+    for (const line of text.split('\n')) {
+        if (!line.includes('-title"'))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.type === 'custom-title' && typeof rec.customTitle === 'string' && rec.customTitle.trim())
+            custom = rec.customTitle.trim();
+        if (rec.type === 'ai-title' && typeof rec.aiTitle === 'string' && rec.aiTitle.trim())
+            ai = rec.aiTitle.trim();
+    }
+    return custom ?? ai;
+}
 /**
  * Shared mtime+size cache lookup for the two session-file formats. `parseFull` runs only on a
- * cache miss with a fresh read; `makeTruncated` builds a summary-only result when the file is
- * over the per-file cap or the per-request byte budget is exhausted. A size-cap truncation is
+ * cache miss with a fresh read. When the file is over the per-file cap or the per-request byte
+ * budget is exhausted, `parseFull` runs on just the head slice (prompt, cwd, branch, model all
+ * live near the top) and the last chat time comes from the tail slice. A size-cap truncation is
  * deterministic (depends only on the file) and gets cached; a budget-cap truncation depends on
  * request ordering, so it is *not* cached — a later request with a fresh budget may read it fully.
  */
-async function cachedParse(file, cache, budget, parseFull, makeTruncated) {
+async function cachedParse(file, cache, budget, parseFull) {
+    const truncated = async () => {
+        const r = parseFull(await readHead(file), st);
+        const tail = await readHead(file, HEAD_SCAN_BYTES, true);
+        // a single record can outgrow the head slice, so look for the SDK marker in the tail too
+        const automated = r.meta.automated || /"entrypoint":"sdk/.test(tail);
+        const title = sessionTitle(tail) ?? r.meta.title;
+        return { ...r, meta: { ...r.meta, ...(title && { title }), messageCount: 0, lastActivity: lastChatTime(tail) ?? st.mtimeMs, truncated: true, ...(automated && { automated }) } };
+    };
     let st;
     try {
         st = await stat(file);
@@ -87,12 +152,12 @@ async function cachedParse(file, cache, budget, parseFull, makeTruncated) {
     }
     scanCacheMisses++;
     if (st.size > MAX_FILE_SCAN_BYTES) {
-        const result = makeTruncated(st, await readHead(file));
+        const result = await truncated();
         cache.set(file, { mtimeMs: st.mtimeMs, size: st.size, result });
         return result;
     }
     if (st.size > budget.bytesLeft)
-        return makeTruncated(st, await readHead(file)); // not cached — budget is per-request
+        return truncated(); // not cached — budget is per-request
     let raw;
     try {
         raw = await readFile(file, 'utf8');
@@ -110,6 +175,7 @@ async function parseClaudeSession(file, budget) {
     return cachedParse(file, claudeSessionCache, budget, (raw, st) => {
         const lines = raw.split('\n').filter(l => l.trim());
         let firstPrompt = null, gitBranch = null, model = null, cwd = null;
+        let automated = false;
         for (const line of lines) {
             let rec;
             try {
@@ -118,13 +184,15 @@ async function parseClaudeSession(file, budget) {
             catch {
                 continue;
             }
+            if (typeof rec.entrypoint === 'string' && rec.entrypoint.startsWith('sdk'))
+                automated = true;
             if (cwd === null && typeof rec.cwd === 'string')
                 cwd = rec.cwd;
             if (gitBranch === null && typeof rec.gitBranch === 'string')
                 gitBranch = rec.gitBranch;
             if (firstPrompt === null && rec.type === 'user') {
                 const c = rec.message?.content;
-                const text = typeof c === 'string' ? c : Array.isArray(c) ? c.find((x) => x?.type === 'text')?.text : null;
+                const text = typeof c === 'string' ? c : Array.isArray(c) ? c.find((x) => x?.type === 'text' && !String(x.text).trimStart().startsWith('<'))?.text : null;
                 if (typeof text === 'string' && text.trim() && !text.trimStart().startsWith('<'))
                     firstPrompt = text.trim().slice(0, 200);
             }
@@ -133,8 +201,9 @@ async function parseClaudeSession(file, budget) {
             if (firstPrompt && model && gitBranch && cwd)
                 break;
         }
-        return { meta: { id, mtime: st.mtimeMs, messageCount: lines.length, firstPrompt, gitBranch, model, sizeBytes: st.size }, cwd };
-    }, (st, head) => ({ meta: { id, mtime: st.mtimeMs, messageCount: 0, firstPrompt: null, gitBranch: null, model: null, sizeBytes: st.size, truncated: true }, cwd: headCwd(head, r => r.cwd) }));
+        const lastActivity = lastChatTime(raw) ?? st.mtimeMs;
+        return { meta: { id, mtime: st.mtimeMs, lastActivity, messageCount: lines.length, title: sessionTitle(raw), firstPrompt, gitBranch, model, sizeBytes: st.size, ...(automated && { automated }) }, cwd };
+    });
 }
 async function scanProjectsDir(projectsDir, scope, budget) {
     if (!existsSync(projectsDir))
@@ -172,7 +241,7 @@ async function scanProjectsDir(projectsDir, scope, budget) {
         }
         if (!sessions.length)
             continue;
-        sessions.sort((a, b) => b.mtime - a.mtime);
+        sessions.sort((a, b) => b.lastActivity - a.lastActivity);
         out.push({ agent: 'claude', scope, project: cwd ?? decodeProjectDir(proj.name), sessions });
     }
     return out;
@@ -280,9 +349,14 @@ async function parseCodexTranscript(file, scope) {
     let project = '(unknown project)';
     const hasResponseMessages = records.some(rec => rec?.type === 'response_item' && rec?.payload?.type === 'message');
     const messages = [];
+    let seenMeta = false;
     for (const rec of records) {
         const payload = rec?.payload;
         if (rec?.type === 'session_meta') {
+            // a sub-agent thread replays its parent's session_meta after its own — the first is ours
+            if (seenMeta)
+                continue;
+            seenMeta = true;
             if (typeof payload?.id === 'string')
                 id = payload.id;
             else if (typeof payload?.session_id === 'string')
@@ -317,6 +391,7 @@ async function parseCodexSession(file, budget) {
         const lines = raw.split('\n').filter(l => l.trim());
         let id = null, firstPrompt = null, gitBranch = null;
         let model = null, cwd = null, messageCount = 0;
+        let seenMeta = false, automated = false;
         for (const line of lines) {
             let rec;
             try {
@@ -326,7 +401,10 @@ async function parseCodexSession(file, budget) {
                 continue;
             }
             const payload = rec?.payload;
-            if (rec?.type === 'session_meta') {
+            // a sub-agent thread replays its parent's session_meta after its own — the first is ours
+            if (rec?.type === 'session_meta' && !seenMeta) {
+                seenMeta = true;
+                automated = payload?.thread_source === 'subagent' || payload?.source?.subagent !== undefined;
                 if (typeof payload?.id === 'string')
                     id = payload.id;
                 else if (typeof payload?.session_id === 'string')
@@ -347,7 +425,7 @@ async function parseCodexSession(file, budget) {
                 messageCount++;
                 if (firstPrompt === null && payload.role === 'user') {
                     const text = messageText(payload.content);
-                    if (text?.trim() && !text.trimStart().startsWith('<'))
+                    if (text?.trim() && !/^\s*(<|# AGENTS\.md instructions)/.test(text))
                         firstPrompt = text.trim().slice(0, 200);
                 }
             }
@@ -357,8 +435,8 @@ async function parseCodexSession(file, budget) {
             }
         }
         id ??= fallbackId;
-        return { meta: { id, mtime: st.mtimeMs, messageCount: messageCount || lines.length, firstPrompt, gitBranch, model, sizeBytes: st.size }, cwd };
-    }, (st, head) => ({ meta: { id: fallbackId, mtime: st.mtimeMs, messageCount: 0, firstPrompt: null, gitBranch: null, model: null, sizeBytes: st.size, truncated: true }, cwd: headCwd(head, r => r?.payload?.cwd) }));
+        return { meta: { id, mtime: st.mtimeMs, lastActivity: lastChatTime(raw) ?? st.mtimeMs, messageCount: messageCount || lines.length, firstPrompt, gitBranch, model, sizeBytes: st.size, ...(automated && { automated }) }, cwd };
+    });
 }
 async function codexSessionFiles(dir) {
     let entries;
@@ -411,7 +489,7 @@ async function scanCodexSessionsDir(sessionsDir, scope, budget) {
     }
     return [...byProject.entries()].map(([project, sessions]) => ({
         agent: 'codex', scope, project,
-        sessions: sessions.sort((a, b) => b.mtime - a.mtime),
+        sessions: sessions.sort((a, b) => b.lastActivity - a.lastActivity),
     }));
 }
 export async function scanSessions(opts) {
@@ -433,7 +511,36 @@ export async function scanSessions(opts) {
             ? await scanCodexSessionsDir(sessionDir, p.name, budget)
             : await scanProjectsDir(sessionDir, p.name, budget));
     }
-    return out;
+    return out.sort((a, b) => b.sessions[0].lastActivity - a.sessions[0].lastActivity);
+}
+/** The `limit` sessions you chatted in most recently, across every project and profile. */
+export function recentSessions(rows, limit = 10) {
+    return rows
+        .flatMap(p => p.sessions.filter(s => !s.automated).map(session => ({ agent: p.agent, scope: p.scope, project: p.project, session })))
+        .sort((a, b) => b.session.lastActivity - a.session.lastActivity)
+        .slice(0, limit);
+}
+const shq = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
+/**
+ * Paste-ready command that reopens a session in its own project under the profile that owns it.
+ * Prefers the profile's launcher (it carries provider env and secrets); otherwise points the
+ * agent at the profile dir directly. `owner` is null when no declared profile matches the scope.
+ */
+export function resumeCommand(r, owner) {
+    const resume = r.agent === 'codex' ? `resume ${r.session.id}` : `--resume ${r.session.id}`;
+    const bin = r.agent === 'codex' ? 'codex' : 'claude';
+    const run = owner?.launcher ? `${owner.launcher} ${resume}`
+        : owner ? `${r.agent === 'codex' ? 'CODEX_HOME' : 'CLAUDE_CONFIG_DIR'}=${shq(owner.dir)} ${bin} ${resume}`
+            : `${bin} ${resume}`;
+    return r.project.startsWith('/') ? `cd ${shq(r.project)} && ${run}` : run;
+}
+/**
+ * Which profile reopens a session: the one named by its scope, or — for the shared pool — the
+ * first profile of the same agent that shares sessions.
+ */
+export function sessionOwner(r, profiles) {
+    const same = profiles.filter(p => (p.agent ?? 'claude') === r.agent);
+    return (r.scope === 'shared' ? same.find(p => p.sharedSessions) : same.find(p => p.name === r.scope)) ?? null;
 }
 /** Read visible conversation and tool activity for one known managed session. */
 export async function readSessionTranscript(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccprofiles-core",
-  "version": "0.10.3",
+  "version": "0.12.0",
   "description": "Core library for ccprofiles — discovery, manifest, secrets, apply, and LAN sync for Claude Code multi-account setups",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,7 +38,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "smol-toml": "^1.7.0",
+    "smol-toml": "^1.9.0",
     "yaml": "^2.5.0",
     "zod": "^3.23.0"
   },