total-recall-brain 3.28.2 → 3.30.1

package/src/core/scheduler.mjs

@@ -189,24 +189,40 @@ export function persistTaskToDisk(task, queueDir) {
   return filepath;
 }
 
+// ─── Research Pipeline ──────────────────────────────────────────────────────────
+
+/** A failed research item is retried at most this many times, then stays failed. */
+export const MAX_RESEARCH_ATTEMPTS = 3;
+
+/**
+ * The research pipeline. It ends at improvement: there is deliberately no
+ * monitoring or expansion phase, because research must never spawn research.
+ */
+export const RESEARCH_PHASES = Object.freeze({
+  acquisition: {
+    step: 1, label: 'Acquisition', category: 'proactive-research',
+    body: (i) => `Run knowledge acquisition cycle for queued topic: ${i.topic}.\nNotes: ${i.notes || 'None'}`,
+  },
+  deliberation: {
+    step: 2, label: 'Deliberation', category: 'system2-deliberation',
+    body: (i) => `Run deep System 2 cognitive deliberation for topic: ${i.topic}.\nTarget node: ${i.node_slug || 'pending'}`,
+  },
+  improvement: {
+    step: 3, label: 'Improvement', category: 'memory-maintenance',
+    body: (i) => `Run document improvement and formatting refinement for topic: ${i.topic}.\nTarget node: ${i.node_slug || 'pending'}`,
+  },
+});
+const RESEARCH_PHASE_COUNT = Object.keys(RESEARCH_PHASES).length;
+
 // ─── Idle Task Generation ───────────────────────────────────────────────────────
 
 let _idleCycleCounter = 0;
 
 /**
  * Generate an idle improvement task when the explicit queue is empty.
- * Weighted toward proactive research — 3 of every 9 ticks do real web search.
- *
- * Cycle (9 ticks):
- *   0: proactive-research   — web search + synthesize from agenda
- *   1: inference            — draw System 2 conclusions from vault clusters
- *   2: proactive-research   — web search (second topic)
- *   3: staleness-check      — flag outdated facts
- *   4: proactive-research   — web search (third topic)
- *   5: inference            — draw more conclusions
- *   6: post-mortem          — re-analyze most recent session
- *   7: clarity-review       — improve a vault node
- *   8: cutoff-audit         — check for training-drift
+ * Purely local maintenance, round-robin: inference, post-mortem, clarity
+ * review, memory compaction. Idle ticks never research on their own; research
+ * only runs for topics a human asked for or the project gate approved.
  */
 export function generateIdleTask({ vaultDir, sessionsDir }) {
   // Only allow purely local task generation strategies.
@@ -229,23 +245,6 @@ export function generateIdleTask({ vaultDir, sessionsDir }) {
   }
 }
 
-/**
- * Generate a proactive research task — pulls the next topic from the agenda
- * and queues a full web search + synthesis cycle.
- */
-function generateProactiveResearchTask() {
-  return {
-    type: 'task',
-    slug: `proactive-research-${Date.now().toString(36)}`,
-    priority: 55,
-    category: 'proactive-research',
-    status: 'pending',
-    created_by: 'scheduler-idle',
-    reason: 'Idle task: pull next topic from research agenda and execute web search + synthesis.',
-    body: 'Run one knowledge acquisition cycle: pull highest-priority pending topic from agenda, gather from web/wikipedia/arXiv/npm/github, synthesize with LLM, write cited fact node to vault.',
-  };
-}
-
 /**
  * Pick a random active memory node and create a clarity review task.
  */
@@ -285,54 +284,6 @@ function generateMemoryCompactionTask(vaultDir) {
   };
 }
 
-/**
- * Pick the oldest fact node and create a staleness check task.
- */
-function generateStalenessCheckTask(vaultDir) {
-  const nodes = getNodes(vaultDir)
-    .filter((n) => n.status === 'active' && n.category === 'facts')
-    .sort((a, b) => {
-      const aDate = new Date(a.last_accessed || a.updated || 0).getTime();
-      const bDate = new Date(b.last_accessed || b.updated || 0).getTime();
-      return aDate - bDate; // oldest first
-    });
-
-  if (nodes.length === 0) {
-    // No facts? Pick any old node
-    const allNodes = getNodes(vaultDir).filter((n) => n.status === 'active');
-    if (allNodes.length === 0) {
-      return makeFallbackTask('research-acquisition', 'No facts to verify');
-    }
-    const oldest = allNodes.sort((a, b) => {
-      return new Date(a.updated || 0).getTime() - new Date(b.updated || 0).getTime();
-    })[0];
-    return {
-      type: 'task',
-      slug: `staleness-check-${oldest.slug}-${Date.now().toString(36)}`,
-      priority: 25,
-      category: 'research-acquisition',
-      target: oldest.slug,
-      status: 'pending',
-      created_by: 'scheduler-idle',
-      reason: `Idle task: verify if "${oldest.title}" is still current.`,
-      body: `## Objective\nEvaluate whether memory node "${oldest.slug}" is still accurate given its age and domain.`,
-    };
-  }
-
-  const target = nodes[0];
-  return {
-    type: 'task',
-    slug: `staleness-check-${target.slug}-${Date.now().toString(36)}`,
-    priority: 25,
-    category: 'research-acquisition',
-    target: target.slug,
-    status: 'pending',
-    created_by: 'scheduler-idle',
-    reason: `Idle task: verify if fact "${target.title}" is still current.`,
-    body: `## Objective\nThis fact was last accessed on ${target.last_accessed || 'unknown'}.\nDetermine if it is: STILL_VALID, POSSIBLY_STALE, or LIKELY_OUTDATED.\nIf stale, suggest a verification search query.`,
-  };
-}
-
 /**
  * Pick a cluster of related nodes and create an inference task.
  */
@@ -499,107 +450,70 @@ export function createScheduler({ queueDir, vaultDir, sessionsDir }) {
     });
   }
 
-  // Load pending research queue tasks
+  // Load pending research queue tasks.
+  //
+  // Research ends when it is answered: acquisition → deliberation → improvement →
+  // done. Nothing here re-opens finished work. (A `done` item used to be reset to
+  // a monitoring pass every hour, forever, and the expansion phase spawned three
+  // new topics per finished one — see docs/projects/.../RESEARCH_SYSTEM2_AUDIT.md.)
+  // Failed items retry after a cooldown, at most MAX_RESEARCH_ATTEMPTS times.
   try {
     const COOLDOWN_MS = process.env.RESEARCH_COOLDOWN_MS
       ? parseInt(process.env.RESEARCH_COOLDOWN_MS, 10)
       : 60 * 60 * 1000; // 1 hour default
 
-    const allItems = loadQueue();
     let resetCount = 0;
-
-    for (const item of allItems) {
-      if (item.status === 'done' || item.status === 'failed') {
-        const completedTime = new Date(item.completed_at || item.updated_at || 0).getTime();
-        if (Date.now() - completedTime < COOLDOWN_MS) continue;
-
-        // Empty "done" (no node, no conclusions) is NOT real research — re-acquire
-        const emptyDone =
-          item.status === 'done' &&
-          !item.node_slug &&
-          !(item.summary?.conclusions?.length > 0);
-
-        // Successful done with real content: re-queue only for monitoring refresh, keep node
-        // Failed or empty: force acquisition from scratch
-        try {
-          if (emptyDone || item.status === 'failed' || !item.node_slug) {
-            updateQueueItem(item.id, {
-              status: 'pending',
-              research_phase: 'acquisition',
-              notes: emptyDone
-                ? 'Auto-reset empty done project → re-run acquisition (previous run produced no memory node)'
-                : item.notes || null,
-            });
-          } else {
-            // Has a real node — optional re-monitor after cooldown (don't wipe conclusions)
-            updateQueueItem(item.id, {
-              status: 'pending',
-              research_phase: 'monitoring',
-            });
-          }
-          resetCount++;
-        } catch (updateErr) {
-          logger.error({
-            subsystem: 'scheduler',
-            message: `Failed to reset research queue item ${item.id} to pending: ${updateErr.message}`,
-          });
-        }
+    for (const item of loadQueue()) {
+      if (item.status !== 'failed') continue;
+      if ((item.attempts || 0) >= MAX_RESEARCH_ATTEMPTS) continue;
+      const failedAt = new Date(item.updated_at || item.created_at || 0).getTime();
+      if (Date.now() - failedAt < COOLDOWN_MS) continue;
+      try {
+        updateQueueItem(item.id, {
+          status: 'pending',
+          research_phase: item.node_slug ? (item.research_phase || 'acquisition') : 'acquisition',
+          attempts: (item.attempts || 0) + 1,
+        });
+        resetCount++;
+      } catch (updateErr) {
+        logger.error({
+          subsystem: 'scheduler',
+          message: `Failed to retry research queue item ${item.id}: ${updateErr.message}`,
+        });
       }
     }
-
     if (resetCount > 0) {
       logger.info({
         subsystem: 'scheduler',
-        message: `Auto-reset ${resetCount} research items after cooldown (empty→acquisition, failed→acquisition, done+node→monitoring).`,
+        message: `Retrying ${resetCount} failed research items (max ${MAX_RESEARCH_ATTEMPTS} attempts each).`,
       });
     }
 
+    // User requests run before autonomous background research; oldest first within each.
     const researchItems = loadQueue()
-      .filter((i) => i.status === 'pending')
-      .sort((a, b) => new Date(a.updated_at || a.created_at || 0).getTime() - new Date(b.updated_at || b.created_at || 0).getTime());
+      .filter((i) => i.status === 'pending' && RESEARCH_PHASES[i.research_phase || 'acquisition'])
+      .sort((a, b) => {
+        const ua = a.origin === 'autonomous' ? 1 : 0;
+        const ub = b.origin === 'autonomous' ? 1 : 0;
+        if (ua !== ub) return ua - ub;
+        return new Date(a.updated_at || a.created_at || 0).getTime() - new Date(b.updated_at || b.created_at || 0).getTime();
+      });
 
     for (let idx = 0; idx < researchItems.length; idx++) {
       const item = researchItems[idx];
-      const dynamicPriority = 85 + (researchItems.length - idx);
       const phase = item.research_phase || 'acquisition';
-
-      let category = 'proactive-research';
-      let slug = `research-acquisition-${item.id}`;
-      let reason = `Queued research project (Phase 1/5: Acquisition): ${item.topic}`;
-      let body = `Run knowledge acquisition cycle for queued topic: ${item.topic}.\nNotes: ${item.notes || 'None'}`;
-
-      if (phase === 'deliberation') {
-        category = 'system2-deliberation';
-        slug = `research-deliberation-${item.id}`;
-        reason = `Queued research project (Phase 2/5: Deliberation): ${item.topic}`;
-        body = `Run deep System 2 cognitive deliberation for topic: ${item.topic}.\nTarget node: ${item.node_slug || 'pending'}`;
-      } else if (phase === 'improvement') {
-        category = 'memory-maintenance';
-        slug = `research-improvement-${item.id}`;
-        reason = `Queued research project (Phase 3/5: Improvement): ${item.topic}`;
-        body = `Run document improvement and formatting refinement for topic: ${item.topic}.\nTarget node: ${item.node_slug || 'pending'}`;
-      } else if (phase === 'monitoring') {
-        category = 'proactive-research';
-        slug = `research-monitoring-${item.id}`;
-        reason = `Queued research project (Phase 4/5: Monitoring): ${item.topic}`;
-        body = `Identify reliable sources of ongoing information, news, feeds or release notes for: ${item.topic}.\nTarget node: ${item.node_slug || 'pending'}`;
-      } else if (phase === 'expansion') {
-        category = 'exploration';
-        slug = `research-expansion-${item.id}`;
-        reason = `Queued research project (Phase 5/5: Expansion): ${item.topic}`;
-        body = `Discover adjacent research domains, brainstorm tangents, and auto-spawn follow-up tasks for: ${item.topic}.\nTarget node: ${item.node_slug || 'pending'}`;
-      }
+      const spec = RESEARCH_PHASES[phase];
 
       queue.enqueue({
         type: 'task',
-        slug,
-        priority: dynamicPriority,
-        category,
+        slug: `research-${phase}-${item.id}`,
+        priority: 85 + (researchItems.length - idx),
+        category: spec.category,
         target: item.topic,
         status: 'pending',
         created_by: 'research-queue',
-        reason,
-        body,
+        reason: `Queued research project (Phase ${spec.step}/${RESEARCH_PHASE_COUNT}: ${spec.label}): ${item.topic}`,
+        body: spec.body(item),
         _research_id: item.id,
         _research_phase: phase,
         _node_slug: item.node_slug,

package/src/core/schema.mjs

@@ -1043,6 +1043,8 @@ export const MeshNodeSchema = z.object({
   /** Snapshot of host NICs (kinds are classified heuristically). */
   interfaces: z.array(NetworkInterfaceEntrySchema).optional(),
   lan_ip: z.string().nullable().optional(),
+  /** Port of this node's brain HTTP service, for mesh service discovery. */
+  brain_port: z.number().int().positive().max(65535).nullable().optional(),
   /**
    * Device I/O profile — entity variables for agent UI generation
    * (touchscreen, mic, speaker, screen, keyboard, …).
@@ -1064,6 +1066,125 @@ export const DaemonLeaderSchema = z.object({
   lease_ttl_seconds: z.number().int().positive().default(60),
 }).passthrough();
 
+/**
+ * Install record for one plugin. Lives beside the plugin, in the vault of the
+ * brain that owns its plugins directory: `system/plugins/<id>.md`.
+ * Every field is a fact this node observed — there is deliberately no rating,
+ * review, or popularity data anywhere in the plugin model.
+ */
+export const PluginRecordSchema = z.object({
+  type: z.literal('plugin_record'),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  timestamp: ssssDatetime(),
+  plugin_id: z.string().regex(/^[a-z][a-z0-9-]{1,63}$/),
+  version: z.string().min(1),
+  scope: z.enum(['project', 'global']),
+  /** Legacy private mesh sharing. Public sharing requires a separate opt-in. */
+  shared: z.boolean().default(false),
+  public_shared: z.boolean().default(false),
+  source: z.object({
+    kind: z.enum(['bundled', 'public', 'peer', 'git', 'local', 'link']),
+    ref: z.string().min(1),
+    peer_hostname: z.string().nullable().optional(),
+  }).passthrough(),
+  /** Content hash at install time (see plugin-bundle.mjs). */
+  sha256: z.string().regex(/^[0-9a-f]{64}$/).nullable().optional(),
+  installed_at: ssssDatetime(),
+  /** Last minute-slot (YYYY-MM-DDTHH:MM) each scheduled task command ran in. */
+  task_runs: z.record(z.string()).optional(),
+}).passthrough();
+
+const SECRET_KEY_PATTERN = /^(.*_)?(secret|token|password|api[_-]?key|private[_-]?key|credentials|auth[_-]?header|bearer)$/i;
+
+function hasProhibitedSecretData(obj) {
+  if (!obj || typeof obj !== 'object') return false;
+  for (const [key, value] of Object.entries(obj)) {
+    if (SECRET_KEY_PATTERN.test(key) && value) return true;
+    if (typeof value === 'object' && hasProhibitedSecretData(value)) return true;
+  }
+  return false;
+}
+
+/**
+ * App-local capability installation record.
+ * Lives in the application's vault (e.g. `system/capabilities/<id>.md`).
+ * Tracks installed version, source hash, adapter, granted access, generated files, and state.
+ * Strictly prohibits raw credentials and secret values.
+ */
+export const AppCapabilityInstallationSchema = z.object({
+  type: z.literal('app_capability_installation'),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  timestamp: ssssDatetime(),
+  capability_id: z.string().regex(/^[a-z][a-z0-9-]{1,63}$/),
+  version: z.string().min(1),
+  source_sha256: z.string().regex(/^[0-9a-f]{64}$/),
+  adapter: z.string().min(1),
+  status: z.enum(['installing', 'installed', 'failed', 'upgrading', 'upgrade_failed', 'uninstalled', 'repair_needed']),
+  access_grants: z.array(z.string()).default([]),
+  resources: z.record(z.any()).optional().default({}),
+  files: z.array(z.object({
+    path: z.string(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    size: z.number().int().nonnegative().optional()
+  })).default([]),
+  plan_hash: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+  installed_at: ssssDatetime(),
+  updated_at: ssssDatetime().optional(),
+  error: z.string().nullable().optional()
+}).passthrough().superRefine((data, ctx) => {
+  if (hasProhibitedSecretData(data.resources)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Security error: Prohibited credential or secret value detected in capability resources. Installation records must not store plaintext secrets.'
+    });
+  }
+});
+
+/**
+ * App-local access grant record.
+ * Grants a capability or principal explicit access to specific scopes and resources.
+ */
+export const AccessGrantSchema = z.object({
+  type: z.literal('access_grant'),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  timestamp: ssssDatetime(),
+  grantee: z.string().min(1),
+  grantee_type: z.enum(['capability', 'agent', 'service', 'user']).default('capability'),
+  scopes: z.array(z.string()).min(1),
+  resources: z.array(z.string()).optional().default([]),
+  status: z.enum(['active', 'revoked', 'expired']).default('active'),
+  granted_at: ssssDatetime(),
+  granted_by: z.string().min(1),
+  expires_at: ssssDatetimeNullable().optional()
+}).passthrough();
+
+/**
+ * Canonical repo-layer skill configuration record.
+ * Persisted as an SSSS document in the project vault (e.g. `system/skills/<id>.md`).
+ * Controls gate commands, tier rules, and repo customizations.
+ * Projected into `config.json` for skill scripts to read.
+ */
+export const SkillConfigSchema = z.object({
+  type: z.literal('skill_config'),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  timestamp: ssssDatetime(),
+  skill_id: z.string().regex(/^[a-z][a-z0-9-]{1,63}$/),
+  version: z.string().min(1),
+  config: z.record(z.any()).default({}),
+  tiers: z.record(z.any()).optional().default({}),
+  gates: z.array(z.object({
+    name: z.string(),
+    command: z.string(),
+    tier: z.string().optional()
+  })).optional().default([]),
+  created_at: ssssDatetime(),
+  updated_at: ssssDatetime().optional()
+}).passthrough();
+
 // ─── Schema Registry (§5 of the SSSS spec) ─────────────────────────────────
 
 /** Total Recall host-extension primitives; peer hosts are not required to register them. */
@@ -1073,6 +1194,10 @@ export const SSSS_HOST_EXTENSION_TYPES = [
   'notification_rule',
   'mesh_node',
   'daemon_leader',
+  'plugin_record',
+  'app_capability_installation',
+  'access_grant',
+  'skill_config',
 ];
 
 /** Map from SSSS `type` value to its Zod schema. Used by the operation validator. */
@@ -1082,6 +1207,10 @@ export const SSSS_SCHEMAS = {
   notification_rule: NotificationRuleSchema,
   mesh_node: MeshNodeSchema,
   daemon_leader: DaemonLeaderSchema,
+  plugin_record: PluginRecordSchema,
+  app_capability_installation: AppCapabilityInstallationSchema,
+  access_grant: AccessGrantSchema,
+  skill_config: SkillConfigSchema,
   memory: MemoryNodeSchema,
   conflict: ConflictRecordSchema,
   task: TaskSchema,

package/src/core/search.mjs

@@ -155,12 +155,17 @@ export async function semanticSearch(query, {
 
   // 2. Perform Semantic Search Channel (if embedding & index available)
   let semanticRanked = [];
+  // Raw cosine similarity per slug. RRF scores below are rank-based, so the top
+  // hit scores ~0.49 however unrelated it is; callers that must decide whether a
+  // hit is actually relevant (e.g. the browser extension's page recall) need this.
+  const similarityBySlug = new Map();
   if (queryEmbedding && vaultEntries.length > 0) {
     const store = new VectorStore();
     store.load(vaultIndex);
     const matches = store.search(queryEmbedding, filteredNodes.length, filteredSlugs, cosineSimilarity);
     
     semanticRanked = matches.map(({ slug, similarity }) => {
+      similarityBySlug.set(slug, similarity);
       const node = filteredNodes.find(n => n.slug === slug);
       const temporal = computeTemporalBoost(node);
       return { slug, score: similarity * temporal };
@@ -231,7 +236,13 @@ export async function semanticSearch(query, {
   // Slice top results
   for (const { node, score } of blendedRanked.slice(0, k)) {
     if (node) {
-      results.push({ ...node, type: 'vault', score });
+      const similarity = similarityBySlug.get(node.slug);
+      results.push({
+        ...node,
+        type: 'vault',
+        score,
+        ...(similarity !== undefined && { similarity: Math.round(similarity * 1000) / 1000 }),
+      });
     }
   }
 

package/src/core/secret-integration-research.mjs

@@ -289,14 +289,18 @@ export async function maybeEnqueueIntegrationResearch(brainDir, key, meta = {},
     };
   }
 
-  const { addToQueue } = await import('./research-queue.mjs');
-  const item = addToQueue({
-    topic: inference.topic,
-    priority: inference.priority || 'low',
-    notes: inference.notes || `AI-inferred product research for secret \`${key}\`.`,
-    brainDir,
-  });
-  return { enqueued: true, item, inference };
+  // Nobody asked for this, so it goes through the autonomous gate and counts
+  // against the same daily budget as project gap research.
+  const { proposeAutonomousResearch } = await import('./research-gate.mjs');
+  const notes = inference.notes || `AI-inferred product research for secret \`${key}\`.`;
+  const { queued, skipped } = await proposeAutonomousResearch(
+    [{ topic: inference.topic, rationale: notes, priority: inference.priority || 'low' }],
+    { project: null, via: 'secret', brainDir, coverageCheck: opts.coverageCheck },
+  );
+  if (!queued.length) {
+    return { enqueued: false, skipped: skipped[0]?.reason || 'gate declined', inference };
+  }
+  return { enqueued: true, item: queued[0], inference };
 }
 
 /**

package/src/core/secrets-store.mjs

@@ -12,6 +12,7 @@ import crypto from 'crypto';
 import os from 'os';
 import YAML from 'yaml';
 import { encryptSecrets, decryptSecrets, encryptSecretsSync, decryptSecretsSync } from './crypto.mjs';
+import { DEFAULT_KEYCHAIN_SERVICE, readKeychainPassword } from './secrets-keychain.mjs';
 
 const META_KEY = '__tr_secrets_meta';
 
@@ -39,8 +40,81 @@ export function resolveUsagePath(brainDir) {
   return path.join(brainDir, 'logs', 'usage.jsonl');
 }
 
-function secretsPassword() {
-  return process.env.TR_SECRETS_PASSWORD || process.env.TR_MASTER_PASSWORD || null;
+/**
+ * The master password: the environment first, then — on macOS — the Keychain
+ * entry `secret rekey` already maintains (service `total-recall-secrets`,
+ * overridable with TR_SECRETS_KEYCHAIN_SERVICE), then the host env file
+ * (see readTrEnvFilePassword).
+ *
+ * Only an interactive shell profile used to read the Keychain, so a
+ * non-interactive process on the same Mac — a mesh `exec`, a release script —
+ * could not open a store its own user owns. Resolved once per process; the
+ * value is returned to the caller and never logged. TR_SECRETS_NO_KEYCHAIN=1
+ * disables the fallback.
+ */
+let keychainPassword;
+export function secretsPassword({
+  env = process.env,
+  readKeychain = readTrKeychainPassword,
+  readEnvFile = readTrEnvFilePassword,
+} = {}) {
+  const fromEnv = env.TR_SECRETS_PASSWORD || env.TR_MASTER_PASSWORD;
+  if (fromEnv) return fromEnv;
+  if (env.TR_SECRETS_NO_KEYCHAIN !== '1') {
+    let fromKeychain;
+    if (readKeychain !== readTrKeychainPassword) fromKeychain = readKeychain(env) || null;
+    else {
+      if (keychainPassword === undefined) keychainPassword = readKeychain(env) || null;
+      fromKeychain = keychainPassword;
+    }
+    if (fromKeychain) return fromKeychain;
+  }
+  return readEnvFile(env) || null;
+}
+
+/**
+ * The host's env-file carrier: `TR_ENV_FILE`, else `~/.agent/tr.env` — the file
+ * `auto-pull.sh` sources and `secret rekey --env-file` rotates. Only a shell
+ * that sources it used to see the password, so a non-interactive process on a
+ * Linux host (an agent's tool shell, cron, a systemd unit) could not open the
+ * store its own user owns. The file is honoured only when it is a regular file
+ * (not a symlink) that this user owns and no one else can read or write, in a
+ * directory this user owns that no one else can write to.
+ */
+export function readTrEnvFilePassword(env = process.env) {
+  const file = env.TR_ENV_FILE || path.join(env.HOME || os.homedir(), '.agent', 'tr.env');
+  try {
+    // lstat: a symlink could point the carrier at a file someone else controls.
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0) return null;
+    // A directory others can write to lets them replace the file.
+    const dir = fs.statSync(path.dirname(file));
+    if ((dir.mode & 0o022) !== 0) return null;
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (uid !== null && (stat.uid !== uid || dir.uid !== uid)) return null;
+    const line = fs
+      .readFileSync(file, 'utf8')
+      .split(/\r?\n/)
+      .find((entry) => /^\s*(?:export\s+)?TR_SECRETS_PASSWORD\s*=/.test(entry));
+    if (!line) return null;
+    let value = line.slice(line.indexOf('=') + 1).trim();
+    if (value.length >= 2 && /^(['"]).*\1$/.test(value)) value = value.slice(1, -1);
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+function readTrKeychainPassword(env) {
+  if (process.platform !== 'darwin') return null;
+  try {
+    return readKeychainPassword({
+      service: env.TR_SECRETS_KEYCHAIN_SERVICE || DEFAULT_KEYCHAIN_SERVICE,
+      account: env.USER || os.userInfo().username,
+    });
+  } catch {
+    return null;
+  }
 }
 
 /**

package/src/core/session-watcher.mjs

@@ -102,6 +102,7 @@ export function createSessionEntry({
   content,
   role = 'assistant',
   source = 'unknown',
+  cwd = null,
 }) {
   return {
     id: id || crypto.randomBytes(4).toString('hex'),
@@ -111,6 +112,9 @@ export function createSessionEntry({
     content: content || '',
     role,
     source,
+    // Working directory of the agent, when the tool records it. It is how a
+    // session is attributed to a project for project-scoped research.
+    ...(cwd ? { cwd } : {}),
   };
 }
 
@@ -229,6 +233,7 @@ export function parseClaudeCode(filePath) {
         content: content.slice(0, 5000), // cap individual entries
         role,
         source: 'claude-code',
+        cwd: typeof parsed.cwd === 'string' ? parsed.cwd : null,
       }),
     );
   }
@@ -282,6 +287,7 @@ export function parseCodex(filePath) {
         content: content.slice(0, 5000),
         role,
         source: 'codex',
+        cwd: typeof (parsed.cwd || parsed.payload?.cwd) === 'string' ? (parsed.cwd || parsed.payload.cwd) : null,
       }),
     );
     prevId = id;