pi-memory-stone 0.1.3 → 0.1.5

package/src/index.ts

@@ -9,6 +9,7 @@
  *  - Deterministic turn_summary and file_activity capture on agent_end
  *  - FTS5 search
  *  - /memory-status, /memory-search, /memory-open, /memory-inject, /memory-last commands
+ *  - /memory-vault-* commands and natural-language URL capture
  *  - memory_search, memory_open, memory_remember, memory_forget tools
  *  - Conservative same-project before_agent_start injection
  */
@@ -21,6 +22,8 @@ import { retrieve, buildInjectionPacket, formatInjectionForLlm } from "./retriev
 import { getProjectId, getConfig, clearProjectCache } from "./config/index.js";
 import { closeDb, getRecord, insertInjection } from "./db/index.js";
 import { getMemorySessionState, manualRecordsToRankedResults } from "./session-state/index.js";
+import { captureUrlToVault } from "./vault/capture.js";
+import { parseVaultCaptureIntent } from "./vault/intent.js";
 import { createHash } from "node:crypto";
 
 // ─── Session-scoped state ───────────────────────────────────────────
@@ -31,6 +34,37 @@ const injectedRefsThisSession: Set<string> = new Set();
 /** Whether memory injection is temporarily disabled for this session */
 let sessionEnabled = true;
 
+async function maybeCaptureVaultUrl(
+  prompt: string,
+  projectId: string | null,
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const intent = parseVaultCaptureIntent(prompt);
+  if (!intent) return null;
+
+  try {
+    const result = await captureUrlToVault(intent.scope, projectId, cwd, intent.url, { signal });
+    const warnings = result.warnings.length > 0 ? `\nWarnings: ${result.warnings.join("; ")}` : "";
+    return `Captured web page into ${intent.scope} memory vault${result.initialized ? " (initialized vault)" : ""}: ${result.title}\nQuality: ${result.quality} (${result.qualityScore})${warnings}\nPage: ${result.pagePath}\nSource packet: ${result.sourcePacketPath}`;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("[pi-memory-stone] vault URL capture failed:", err);
+    return `Memory vault URL capture failed: ${message}`;
+  }
+}
+
+function vaultCaptureReturn(systemPrompt: string, notice: string) {
+  return {
+    message: {
+      customType: "memory-vault-capture",
+      content: notice,
+      display: true,
+    },
+    systemPrompt: `${systemPrompt}\n\n--- Memory Vault Capture ---\n${notice}\nThe user's vault capture request has already been handled by pi-memory-stone. Briefly confirm the result; do not fetch the same URL again unless the user asks.\n--- End Memory Vault Capture ---`,
+  };
+}
+
 // ─── Extension entry point ─────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
@@ -69,18 +103,24 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("before_agent_start", async (event, ctx) => {
     try {
+      const prompt = event.prompt || "";
+      const projectId = getProjectId(ctx.cwd);
+      const vaultCaptureNotice = await maybeCaptureVaultUrl(prompt, projectId, ctx.cwd, ctx.signal);
+
       // Check if memory is enabled
       const config = getConfig(ctx.cwd);
-      if (!config.enabled) return;
+      if (!config.enabled) {
+        return vaultCaptureNotice ? vaultCaptureReturn(event.systemPrompt || "", vaultCaptureNotice) : undefined;
+      }
 
       const sessionState = getMemorySessionState(ctx.sessionManager.getBranch());
       sessionEnabled = sessionState.enabled;
 
-      if (!sessionEnabled) return;
+      if (!sessionEnabled) {
+        return vaultCaptureNotice ? vaultCaptureReturn(event.systemPrompt || "", vaultCaptureNotice) : undefined;
+      }
 
-      const prompt = event.prompt || "";
       const promptHash = createHash("sha256").update(prompt).digest("hex").slice(0, 12);
-      const projectId = getProjectId(ctx.cwd);
       const injectionMode = sessionState.injectionMode ?? config.injectionMode;
 
       const manualRecords = sessionState.manualRefs
@@ -103,10 +143,11 @@ export default function (pi: ExtensionAPI) {
       }
 
       const selectedResults = [...manualResults, ...autoResults];
-      if (selectedResults.length === 0) return;
-
-      const packet = buildInjectionPacket(selectedResults);
-      const formatted = formatInjectionForLlm(packet, config.maxInjectedTokens);
+      let formatted: string | null = null;
+      if (selectedResults.length > 0) {
+        const packet = buildInjectionPacket(selectedResults);
+        formatted = formatInjectionForLlm(packet, config.maxInjectedTokens);
+      }
 
       // Track only search-selected refs. Manually chosen refs are intentionally
       // injected on every turn until /memory-clear-injected is used.
@@ -114,27 +155,36 @@ export default function (pi: ExtensionAPI) {
         injectedRefsThisSession.add(r.record.id);
       }
 
-      insertInjection({
-        session_id: ctx.sessionManager.getSessionId(),
-        turn_entry_id: ctx.sessionManager.getLeafId() ?? undefined,
-        prompt_hash: promptHash,
-        injected_refs: selectedResults.map((r) => r.record.id).join(","),
-        packet: formatted,
-        reasons: selectedResults.map((r) => r.reasons.join(";")).join(" | "),
-      });
-
-      // Inject as a non-context audit custom entry (separate from LLM context)
-      // but also as a system prompt addition for the LLM
-      const systemPromptAddition = [
-        "",
-        "--- Memory Stone Context ---",
-        formatted,
-        "--- End Memory Stone Context ---",
-      ].join("\n");
-
-      return {
-        systemPrompt: (event.systemPrompt || "") + systemPromptAddition,
-      };
+      if (formatted) {
+        insertInjection({
+          session_id: ctx.sessionManager.getSessionId(),
+          turn_entry_id: ctx.sessionManager.getLeafId() ?? undefined,
+          prompt_hash: promptHash,
+          injected_refs: selectedResults.map((r) => r.record.id).join(","),
+          packet: formatted,
+          reasons: selectedResults.map((r) => r.reasons.join(";")).join(" | "),
+        });
+      }
+
+      if (!formatted && !vaultCaptureNotice) return;
+
+      let systemPrompt = event.systemPrompt || "";
+      if (formatted) {
+        // Inject as a non-context audit custom entry (separate from LLM context)
+        // but also as a system prompt addition for the LLM
+        systemPrompt += [
+          "",
+          "--- Memory Stone Context ---",
+          formatted,
+          "--- End Memory Stone Context ---",
+        ].join("\n");
+      }
+
+      if (vaultCaptureNotice) {
+        return vaultCaptureReturn(systemPrompt, vaultCaptureNotice);
+      }
+
+      return { systemPrompt };
     } catch (err) {
       console.error("[pi-memory-stone] before_agent_start handler error:", err);
     }

package/src/portable/index.ts

@@ -2,10 +2,11 @@
  * Portable export/import/backup helpers for memory records.
  */
 
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
-import { getDb, getDbPath, listRecords, upsertRecord, type RecordRow } from "../db/index.js";
+import { getDb, getDbPath, hardenDbFilePermissions, listRecords, upsertRecord, type RecordRow } from "../db/index.js";
 import { SCHEMA_VERSION, RECORD_KINDS, RECORD_SCOPES, RECORD_STATUSES, type RecordKind, type RecordScope, type RecordStatus } from "../db/schema.js";
+import { isSensitiveForGlobalMemory } from "../privacy/index.js";
 
 export type ExportFormat = "json" | "md";
 
@@ -68,8 +69,8 @@ export function exportMemory(format: ExportFormat, includeInactive = false): str
 export function writeMemoryExport(path: string, format: ExportFormat, includeInactive = false): number {
   const payload = buildMemoryExport(includeInactive);
   const content = format === "json" ? JSON.stringify(payload, null, 2) + "\n" : exportMarkdown(payload);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, content, "utf8");
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, content, { encoding: "utf8", mode: 0o600 });
   return payload.records.length;
 }
 
@@ -94,6 +95,14 @@ export function importMemoryJson(raw: string, options: ImportOptions = {}): Impo
 
     const scope = options.scopeOverride ?? record.scope;
     const projectId = scope === "global" ? null : (options.projectId !== undefined ? options.projectId : record.project_id);
+    if (scope === "project" && !projectId) {
+      result.skipped += 1;
+      continue;
+    }
+    if (scope === "global" && isSensitiveForGlobalMemory(`${record.text}\n${record.tags ?? ""}`)) {
+      result.skipped += 1;
+      continue;
+    }
     const id = upsertRecord({
       kind: record.kind,
       scope,
@@ -117,9 +126,13 @@ export function importMemoryJson(raw: string, options: ImportOptions = {}): Impo
 }
 
 export function backupMemoryDatabase(path: string): void {
-  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   getDb().exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  hardenDbFilePermissions();
   copyFileSync(getDbPath(), path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {}
 }
 
 export function defaultPortablePath(cwd: string, prefix: string, extension: string): string {

package/src/privacy/index.ts

@@ -27,7 +27,7 @@ const SECRET_PATTERNS: { name: string; regex: RegExp; replacement: SecretReplace
   },
   {
     name: "aws-secret",
-    regex: /(?<=SecretAccessKey[=:]\s*)[A-Za-z0-9/+]{40,}/g,
+    regex: /\b(?:aws[_-]?)?secret[_-]?access[_-]?key\b\s*[=:]\s*['"]?[A-Za-z0-9/+=]{40,}['"]?/gi,
     replacement: "[REDACTED:aws-secret]",
   },
   {
@@ -37,12 +37,12 @@ const SECRET_PATTERNS: { name: string; regex: RegExp; replacement: SecretReplace
   },
   {
     name: "generic-api-key",
-    regex: /(?:api[_-]?key|apikey|api[_-]?secret|secret[_-]?key)[=:]\s*['"]?[A-Za-z0-9_\-.]{16,}['"]?/gi,
+    regex: /\b(?:api[_-]?key|apikey|api[_-]?secret|secret[_-]?key|client[_-]?secret|private[_-]?key|access[_-]?key|auth[_-]?key)\b\s*[=:]\s*['"]?[A-Za-z0-9_\-./+=]{16,}['"]?/gi,
     replacement: "[REDACTED:api-key]",
   },
   {
     name: "secret-assignment",
-    regex: /\b(?:secret|secret[_-]?key)\b\s*[=:]\s*(?:['"][^'"]+['"]|[^\s'"`]+)/gi,
+    regex: /\b(?:secret|secret[_-]?key|client[_-]?secret|app[_-]?secret|webhook[_-]?secret|signing[_-]?secret)\b\s*[=:]\s*(?:['"][^'"]+['"]|[^\s'"`]+)/gi,
     replacement: "[REDACTED:secret]",
   },
   {
@@ -126,6 +126,22 @@ export function redactSecrets(text: string): string {
   return result;
 }
 
+export function isSensitiveForGlobalMemory(text: string): boolean {
+  if (redactSecrets(text) !== text) return true;
+
+  return [
+    // Local/absolute/relative filesystem paths and common repo paths.
+    /(?:^|\s)(?:~|\.|\.\.|[A-Za-z]:)?[/\\][^\s]+/,
+    /\b(?:src|lib|test|tests|packages|apps|docs|config)\/[\w./-]+\b/i,
+    /\b[\w.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|yaml|yml|toml|env|db|sqlite|pem|key|crt)\b/i,
+    // Hostnames and network endpoints.
+    /\b(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1)\b/i,
+    /\b[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+(?::\d{2,5})?\b/i,
+    // Implementation/internal detail markers that should stay project-local.
+    /\b(?:internal|private|implementation detail|class|function|method|module|endpoint|schema|table|column)\b/i,
+  ].some((pattern) => pattern.test(text));
+}
+
 export function isSensitivePath(path: string, extraPatterns: RegExp[] = []): boolean {
   const allPatterns = [...DEFAULT_SENSITIVE_PATHS, ...extraPatterns];
 

package/src/retrieval/index.ts

@@ -23,6 +23,8 @@ const KIND_BOOST: Record<string, number> = {
 // ─── Recency decay ──────────────────────────────────────────────────
 
 const RECENCY_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const MAX_RETRIEVAL_LIMIT = 20;
+const MAX_CANDIDATE_LIMIT = MAX_RETRIEVAL_LIMIT * 10;
 
 function recencyDecay(createdAt: number): number {
   const age = Date.now() - createdAt;
@@ -72,7 +74,7 @@ export function rankAndFilter(
     // and require explicit cross-project retrieval.
     if (rec.scope === "global") {
       if (!crossProjectEnabled) continue;
-    } else if (rec.project_id && currentProjectId && rec.project_id !== currentProjectId) {
+    } else if (!rec.project_id || !currentProjectId || rec.project_id !== currentProjectId) {
       continue;
     }
 
@@ -121,6 +123,11 @@ export function rankAndFilter(
 
 // ─── Full retrieval pipeline ────────────────────────────────────────
 
+export function normalizeRetrievalLimit(value: unknown, fallback: number): number {
+  const numeric = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : fallback;
+  return Math.max(1, Math.min(MAX_RETRIEVAL_LIMIT, numeric));
+}
+
 export function retrieve(
   userPrompt: string,
   currentProjectId: string | null,
@@ -133,13 +140,14 @@ export function retrieve(
   },
 ): RankedResult[] {
   const config = getConfig();
-  const limit = opts?.limit ?? config.maxInjectedRecords;
+  const limit = normalizeRetrievalLimit(opts?.limit, config.maxInjectedRecords);
   const crossProject = opts?.crossProjectEnabled ?? config.crossProjectEnabled;
 
   const query = buildSearchQuery(userPrompt, recentFiles);
 
-  // Get more candidates than needed (ranking will filter)
-  const candidates = searchRecordsFts(query, limit * 10, opts?.kindFilter, opts?.scopeFilter);
+  // Get more candidates than needed (ranking will filter), but keep local work bounded.
+  const candidateLimit = Math.min(MAX_CANDIDATE_LIMIT, limit * 10);
+  const candidates = searchRecordsFts(query, candidateLimit, opts?.kindFilter, opts?.scopeFilter);
 
   const ranked = rankAndFilter(candidates, currentProjectId, crossProject);
 

package/src/session-state/index.ts

@@ -67,7 +67,8 @@ export function parseRefArgs(args: string): string[] {
 }
 
 export function isRecordVisibleInProject(record: RecordRow, currentProjectId: string | null): boolean {
-  return record.scope === "global" || record.project_id === null || record.project_id === currentProjectId;
+  if (record.scope === "global") return true;
+  return Boolean(currentProjectId && record.project_id && record.project_id === currentProjectId);
 }
 
 export function manualRecordsToRankedResults(

package/src/tools/index.ts

@@ -6,8 +6,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { getRecord, softForgetRecord, upsertRecord } from "../db/index.js";
-import { retrieve, buildInjectionPacket, formatInjectionForLlm } from "../retrieval/index.js";
+import { retrieve, buildInjectionPacket, formatInjectionForLlm, normalizeRetrievalLimit } from "../retrieval/index.js";
 import { getProjectId, getConfig } from "../config/index.js";
+import { isSensitiveForGlobalMemory } from "../privacy/index.js";
+import { isRecordVisibleInProject } from "../session-state/index.js";
 import type { RecordKind, RecordScope } from "../db/schema.js";
 
 export function registerTools(pi: ExtensionAPI): void {
@@ -37,12 +39,12 @@ export function registerTools(pi: ExtensionAPI): void {
         ] as const),
       ),
       scope: Type.Optional(StringEnum(["project", "global"] as const)),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 5)" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 5, max 20)", minimum: 1, maximum: 20 })),
     }),
     async execute(toolCallId, params, _signal, _onUpdate, ctx) {
       const projectId = getProjectId(ctx.cwd);
       const config = getConfig(ctx.cwd);
-      const limit = params.limit ?? 5;
+      const limit = normalizeRetrievalLimit(params.limit, 5);
 
       const results = retrieve(params.query, projectId, [], {
         limit,
@@ -102,10 +104,8 @@ export function registerTools(pi: ExtensionAPI): void {
       }
 
       const currentProjectId = getProjectId(ctx.cwd);
-      const visibleInCurrentProject =
-        record.scope === "global" || record.project_id === null || record.project_id === currentProjectId;
 
-      if (record.status !== "active" || !visibleInCurrentProject) {
+      if (record.status !== "active" || !isRecordVisibleInProject(record, currentProjectId)) {
         return {
           content: [{ type: "text", text: `Memory record ${params.ref} is not available.` }],
           details: { ref: params.ref, found: false, unavailable: true },
@@ -168,10 +168,7 @@ export function registerTools(pi: ExtensionAPI): void {
       let scope = params.scope ?? "project";
 
       // Safety: never allow global for implementation details, paths, etc.
-      const isSensitiveForGlobal =
-        /\b(?:password|secret|token|key|\.env|localhost|127\.0\.0\.1|internal|private)\b/i.test(
-          params.text,
-        );
+      const isSensitiveForGlobal = isSensitiveForGlobalMemory(`${params.text}\n${params.tags ?? ""}`);
 
       const downgradedToProject = isSensitiveForGlobal && scope === "global";
       if (downgradedToProject) {
@@ -228,14 +225,22 @@ export function registerTools(pi: ExtensionAPI): void {
         };
       }
 
+      const currentProjectId = getProjectId(ctx.cwd);
+      if (record.status !== "active" || !isRecordVisibleInProject(record, currentProjectId)) {
+        return {
+          content: [{ type: "text", text: `Memory record ${params.ref} is not available.` }],
+          details: { ref: params.ref, found: false, unavailable: true },
+        };
+      }
+
       if (params.hard) {
         // For hard delete via tool, we require the user to explicitly confirm
-        // The tool should note this requires user interaction
+        // The tool should note this requires user interaction without leaking record contents.
         return {
           content: [
             {
               type: "text",
-              text: `Permanent deletion requires explicit confirmation. Please use /memory-forget ${params.ref} --hard to permanently delete this record.\n\nRecord: [${record.kind}] ${record.text.slice(0, 200)}`,
+              text: `Permanent deletion requires explicit confirmation. Please use /memory-forget ${params.ref} --hard to permanently delete this record.`,
             },
           ],
           details: { ref: params.ref, requiresConfirmation: true },

package/src/vault/capture.ts

@@ -0,0 +1,268 @@
+/** URL capture for memory vault source pages. */
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { redactSecrets } from "../privacy/index.js";
+import { initVault, getVaultStatus, type VaultRegistry, type VaultRegistryPage } from "./index.js";
+import { sanitizeSlug } from "./markdown.js";
+import { resolveSourcePacketPath, resolveVaultPath, type VaultScope } from "./paths.js";
+import { extractArticle, type ExtractedArticle } from "./extract.js";
+import { assessCaptureQuality, type CaptureQuality, type CaptureQualityReport } from "./quality.js";
+import { fetchCandidate, type CaptureFetchAttempt, type CaptureFetchOptions, type FetchedCandidate } from "./fetch.js";
+import { resolveCaptureTargets, type CaptureCandidate } from "./url-resolvers.js";
+
+const MAX_EXTRACTED_CHARS = 200_000;
+
+export interface CaptureUrlOptions extends CaptureFetchOptions {}
+
+export interface CaptureUrlResult {
+  vaultPath: string;
+  pagePath: string;
+  sourcePacketPath: string;
+  title: string;
+  url: string;
+  finalUrl: string;
+  initialized: boolean;
+  quality: CaptureQuality;
+  qualityScore: number;
+  warnings: string[];
+}
+
+export async function captureUrlToVault(
+  scope: VaultScope,
+  projectId: string | null,
+  cwd: string,
+  url: string,
+  options: CaptureUrlOptions = {},
+): Promise<CaptureUrlResult> {
+  const targets = resolveCaptureTargets(url);
+  const vaultPath = resolveVaultPath(scope, projectId, cwd);
+  const wasInitialized = getVaultStatus(scope, projectId, cwd).initialized;
+  if (!wasInitialized) {
+    initVault(scope, projectId, cwd);
+  }
+
+  const selected = await fetchAndExtractBest(targets.candidates, options);
+  const title = selected.extracted.title || new URL(selected.fetched.finalUrl).hostname;
+  const slug = sanitizeSlug(title).slice(0, 70) || "captured-page";
+  const captureId = `SRC-${new Date().toISOString().slice(0, 10)}-${sha256(targets.originalUrl).slice(0, 8)}`;
+  const packetPath = resolveSourcePacketPath(scope, projectId, cwd, captureId);
+  const packetRelPath = normalizePath(relative(vaultPath, packetPath));
+  const sourcePageRelPath = join("sources", `${slug}-${sha256(targets.originalUrl).slice(0, 8)}.md`);
+  const sourcePagePath = join(vaultPath, sourcePageRelPath);
+
+  mkdirSync(join(packetPath, "original"), { recursive: true, mode: 0o700 });
+  mkdirSync(join(packetPath, "attachments"), { recursive: true, mode: 0o700 });
+  mkdirSync(join(vaultPath, "sources"), { recursive: true, mode: 0o700 });
+
+  const capturedAt = new Date().toISOString();
+  const originalName = originalArtifactName(selected.fetched.contentType, selected.fetched.finalUrl, selected.extracted.extractor);
+  const extractedMarkdown = unescapeRedactionMarkers(redactSecrets(selected.extracted.markdown)).slice(0, MAX_EXTRACTED_CHARS);
+  const redactedRaw = redactSecrets(selected.fetched.raw);
+  const contentHash = sha256(extractedMarkdown);
+
+  const manifest = {
+    id: captureId,
+    url: targets.originalUrl,
+    canonical_url: selected.extracted.canonicalUrl ?? selected.fetched.finalUrl,
+    final_url: selected.fetched.finalUrl,
+    title,
+    byline: selected.extracted.byline,
+    site_name: selected.extracted.siteName,
+    excerpt: selected.extracted.excerpt,
+    published_at: selected.extracted.publishedAt,
+    content_type: selected.fetched.contentType,
+    captured_at: capturedAt,
+    original: `original/${originalName}`,
+    extracted: "extracted.md",
+    metadata: "metadata.json",
+    attempts: selected.attempts,
+    extraction: {
+      extractor: selected.extracted.extractor,
+      strategy: selected.fetched.candidate.strategy,
+      candidate_kind: selected.fetched.candidate.kind,
+    },
+    quality: selected.quality,
+    content_hash: contentHash,
+  };
+
+  const metadata = {
+    title,
+    byline: selected.extracted.byline,
+    site_name: selected.extracted.siteName,
+    excerpt: selected.extracted.excerpt,
+    published_at: selected.extracted.publishedAt,
+    source_url: targets.originalUrl,
+    canonical_url: selected.extracted.canonicalUrl ?? selected.fetched.finalUrl,
+    final_url: selected.fetched.finalUrl,
+    content_hash: contentHash,
+    extractor: selected.extracted.extractor,
+    fetch_strategy: selected.fetched.candidate.strategy,
+    quality: selected.quality,
+  };
+
+  writeFileSync(join(packetPath, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", { mode: 0o600 });
+  writeFileSync(join(packetPath, "metadata.json"), JSON.stringify(metadata, null, 2) + "\n", { mode: 0o600 });
+  writeFileSync(join(packetPath, "original", originalName), redactedRaw, { mode: 0o600 });
+  writeFileSync(join(packetPath, "extracted.md"), extractedMarkdown, { mode: 0o600 });
+
+  const pageMarkdown = renderSourcePage({
+    title,
+    url: targets.originalUrl,
+    canonicalUrl: selected.extracted.canonicalUrl ?? selected.fetched.finalUrl,
+    capturedAt,
+    captureId,
+    packetRelPath,
+    extractedMarkdown,
+    quality: selected.quality,
+    warnings: selected.quality.warnings,
+  });
+  writeFileSync(sourcePagePath, pageMarkdown, { mode: 0o600 });
+
+  updateRegistry(vaultPath, {
+    path: normalizePath(sourcePageRelPath),
+    title,
+    kind: "web_source",
+    source_url: targets.originalUrl,
+    source_packet: packetRelPath,
+    content_hash: sha256(pageMarkdown),
+    generated: true,
+    created_at: capturedAt,
+    updated_at: capturedAt,
+  });
+
+  return {
+    vaultPath,
+    pagePath: sourcePagePath,
+    sourcePacketPath: packetPath,
+    title,
+    url: targets.originalUrl,
+    finalUrl: selected.fetched.finalUrl,
+    initialized: !wasInitialized,
+    quality: selected.quality.quality,
+    qualityScore: selected.quality.score,
+    warnings: selected.quality.warnings,
+  };
+}
+
+interface ExtractedCandidate {
+  fetched: FetchedCandidate;
+  extracted: ExtractedArticle;
+  quality: CaptureQualityReport;
+  attempts: CaptureFetchAttempt[];
+}
+
+async function fetchAndExtractBest(candidates: CaptureCandidate[], options: CaptureUrlOptions): Promise<ExtractedCandidate> {
+  const allAttempts: CaptureFetchAttempt[] = [];
+  let best: ExtractedCandidate | null = null;
+  const errors: string[] = [];
+
+  for (const candidate of candidates) {
+    try {
+      const fetched = await fetchCandidate(candidate, options);
+      allAttempts.push(...fetched.attempts);
+      const redactedRaw = redactSecrets(fetched.raw);
+      const extracted = extractArticle({
+        raw: redactedRaw,
+        contentType: fetched.contentType,
+        url: fetched.finalUrl,
+        candidateKind: candidate.kind,
+      });
+      const quality = assessCaptureQuality({
+        title: extracted.title,
+        markdown: extracted.markdown,
+        extractor: extracted.extractor,
+      });
+      const current: ExtractedCandidate = { fetched, extracted, quality, attempts: [...allAttempts] };
+      if (!best || current.quality.score > best.quality.score) best = current;
+      if (quality.quality === "good") return current;
+    } catch (error) {
+      const attempts = (error as Error & { attempts?: CaptureFetchAttempt[] }).attempts;
+      if (attempts) allAttempts.push(...attempts);
+      errors.push(`${candidate.strategy}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  if (best) return { ...best, attempts: allAttempts };
+  throw new Error(`Unable to fetch article. Attempts failed: ${errors.join("; ")}`);
+}
+
+function renderSourcePage(input: {
+  title: string;
+  url: string;
+  canonicalUrl: string;
+  capturedAt: string;
+  captureId: string;
+  packetRelPath: string;
+  extractedMarkdown: string;
+  quality: CaptureQualityReport;
+  warnings: string[];
+}): string {
+  const warningLines = input.warnings.length > 0
+    ? ["", "Warnings:", ...input.warnings.map((warning) => `- ${warning}`)]
+    : [];
+
+  return [
+    "---",
+    `title: ${JSON.stringify(input.title)}`,
+    "kind: web_source",
+    `source_url: ${JSON.stringify(input.url)}`,
+    `canonical_url: ${JSON.stringify(input.canonicalUrl)}`,
+    `source_packet: ${JSON.stringify(input.packetRelPath)}`,
+    `captured_at: ${JSON.stringify(input.capturedAt)}`,
+    `capture_id: ${JSON.stringify(input.captureId)}`,
+    `quality: ${JSON.stringify(input.quality.quality)}`,
+    `quality_score: ${input.quality.score}`,
+    "generated: true",
+    "source: pi-memory-stone",
+    "---",
+    "",
+    `# ${input.title.replace(/[\r\n]+/g, " ").trim()}`,
+    "",
+    `Source: ${input.url}`,
+    `Canonical: ${input.canonicalUrl}`,
+    `Captured: ${input.capturedAt}`,
+    `Quality: ${input.quality.quality} (${input.quality.score})`,
+    `Source packet: ${input.captureId} (stored outside vault: ${input.packetRelPath})`,
+    ...warningLines,
+    "",
+    "## Extracted text",
+    "",
+    input.extractedMarkdown.trim() || "_No text extracted._",
+    "",
+  ].join("\n");
+}
+
+function updateRegistry(vaultPath: string, page: VaultRegistryPage & {
+  source_url: string;
+  source_packet: string;
+}): void {
+  const registryPath = join(vaultPath, "meta", "registry.json");
+  const registry = JSON.parse(readFileSync(registryPath, "utf8")) as VaultRegistry;
+  const pages = registry.pages.filter((existing) => existing.path !== page.path);
+  pages.push(page);
+  pages.sort((a, b) => a.path.localeCompare(b.path));
+  registry.pages = pages;
+  registry.generated_at = new Date().toISOString();
+  writeFileSync(registryPath, JSON.stringify(registry, null, 2) + "\n", { mode: 0o600 });
+}
+
+function originalArtifactName(contentType: string, finalUrl: string, extractor: string): string {
+  if (contentType.includes("html") || extractor.startsWith("html")) return "response.html";
+  if (contentType.includes("markdown") || finalUrl.toLowerCase().match(/\.(md|markdown|mdx)(?:$|[?#])/) || extractor === "markdown") return "response.md";
+  if (contentType.includes("pdf") || finalUrl.toLowerCase().match(/\.pdf(?:$|[?#])/)) return "response.pdf.txt";
+  return "response.txt";
+}
+
+function normalizePath(path: string): string {
+  return path.split(/[\\/]+/).join("/");
+}
+
+function unescapeRedactionMarkers(markdown: string): string {
+  return markdown.replace(/\\\[REDACTED:([a-z-]+)\\\]/g, "[REDACTED:$1]");
+}
+
+function sha256(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}