swipium 1.4.0 → 2.0.0

package/dist/session/store.js

@@ -1,15 +1,24 @@
-// Session + job + artifact store with DISK PERSISTENCE (DESIGN §3, M6).
+// Session + job + artifact store with DISK PERSISTENCE.
 // Live, non-serializable bits (driver, lastSnapshot, abort controllers) stay in memory;
-// a serializable subset is written to <sessionDir>/state.json on every mutation, and a
-// small registry under ~/.swipium/registry.json lets a fresh server instance reload
-// prior sessions so artifacts/reports/job-status survive a server restart. (A restart does
-// NOT resurrect a running child process — such jobs are marked failed on reload.)
+// a serializable subset is written to <sessionDir>/state.json on mutation (debounced;
+// synchronous for the mutation ledger + session creation + shutdown flush), and a small
+// registry under ~/.swipium/registry.json (lock-guarded, lazily loaded on first access)
+// lets a fresh server instance reload prior sessions so artifacts/reports/job-status survive
+// a server restart. (A restart does NOT resurrect a running child process: such jobs are
+// marked failed on reload, and orphaned Metro pids are verified via `ps` and reaped.)
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { chmodSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { extname, join, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { DEFAULT_RESPONSE_MODE } from '../lib/result.js';
-import { makeRedactor } from '../lib/redact.js';
+import { makeRedactor, redactDeep, redactStructuredText, structuredKindOf } from '../lib/redact.js';
+import { generatedOutputRedactor, inputBindings, inputPlaceholderFor, secretSafeActions, secretSafeNotes, swipiumVarName, } from '../suite/secretGuard.js';
+import { withFileLock, writeFileAtomicSync } from '../lib/lockfile.js';
+import { log } from '../lib/logger.js';
+import { pidOwnedByLiveServer, reclaimPid } from './processRegistry.js';
+import { fixtureMetadata, rehydrateFixtures } from '../fixtures/load.js';
+import { scheduleStartupPrune } from './retention.js';
+import { approvalMechanismFor } from '../consent/consent.js';
 // Phase 2.2 P1.6: budget classes (minutes) keyed by workflow ambition.
 export const BUDGET_PROFILES = {
     guardrail: 8, // guardrail/setup validation
@@ -17,7 +26,7 @@ export const BUDGET_PROFILES = {
     full_smoke: 15, // full authenticated smoke
     install_smoke: 20, // install/boot/rebuild involved
 };
-// Security model (REQ-02): raw secret values (generated passwords/OTPs/tokens) must never touch
+// Security model: raw secret values (generated passwords/OTPs/tokens) must never touch
 // disk. In memory we keep the raw value (for same-session reuse via inputValues), but the
 // serialized form sent to state.json redacts secret values while preserving all reproducibility
 // metadata (varName/field/generator/secret/artifactUri/timestamps). Non-secret generated values
@@ -25,6 +34,36 @@ export const BUDGET_PROFILES = {
 export function serializeGeneratedValues(records) {
     return records.map((r) => (r.secret ? { ...r, value: '<redacted>' } : r));
 }
+/** state.json form of the session's free-text records: raw registered secret values never touch
+ *  disk. Recorded actions go through the same rewrite the generators use (a secret literal typed into
+ *  a non-secure field becomes a secret step with no text); note/finding prose is redacted. URIs,
+ *  paths and numbers are left alone. */
+export function serializeSecretSafe(s) {
+    const toolErrors = s.toolErrors ?? [];
+    const jobs = [...(s.jobs?.values() ?? [])];
+    const envChanges = s.envChanges ?? [];
+    const mutations = s.mutations ?? [];
+    // Fixture values and seed specs are live config, never persisted (not even redacted): a
+    // rehydrated session re-reads them from .swipium/fixtures.json (see fixtures/load.ts).
+    const fixtures = fixtureMetadata(s.fixtures ?? []);
+    if (!s.secrets.size)
+        return { recordedActions: s.recordedActions, notes: s.notes, findings: s.findings, toolErrors, jobs, envChanges, mutations, fixtures };
+    const redact = makeRedactor(s.secrets);
+    const r = (v) => (v ? (redact(v) ?? v) : v);
+    // Structured records (job results, mutation targets, fixtures): strong secrets scrubbed anywhere,
+    // weak (dictionary-like) ones only as a whole value, so package ids / selectors stay intact.
+    const structured = generatedOutputRedactor(s.secrets);
+    return {
+        recordedActions: secretSafeActions(s.recordedActions, s.secrets).actions,
+        notes: secretSafeNotes(s.notes, s.secrets),
+        findings: s.findings.map((f) => ({ ...f, detail: r(f.detail) ?? f.detail, evidence: r(f.evidence) })),
+        toolErrors: toolErrors.map((t) => ({ ...t, message: r(t.message) ?? t.message })),
+        jobs: jobs.map((j) => ({ ...redactDeep(j, structured), error: r(j.error), progress: r(j.progress), resultText: r(j.resultText) })),
+        envChanges: envChanges.map((e) => r(e) ?? e),
+        mutations: mutations.map((m) => ({ ...redactDeep(m, structured), detail: r(m.detail) })),
+        fixtures: redactDeep(fixtures, structured),
+    };
+}
 export const DEFAULT_BUDGET = {
     maxMinutes: 8,
     maxActions: 20,
@@ -40,8 +79,10 @@ export function isTextArtifactMime(mime) {
 }
 export function artifactDirectoryName(kind) {
     switch (kind) {
-        case 'screenshot': return 'screenshots';
-        case 'recording': return 'videos';
+        case 'screenshot':
+            return 'screenshots';
+        case 'recording':
+            return 'videos';
         case 'logs':
         case 'logcat':
         case 'metro':
@@ -51,60 +92,247 @@ export function artifactDirectoryName(kind) {
             return kind;
     }
 }
+/** Filesystem-safe artifact file name (review B5): path separators, NUL/control chars and `..`
+ * runs are replaced, so a caller-supplied name (e.g. a visual baseline name) can never escape
+ * the session directory. Long names are truncated, keeping the extension. */
+export function safeArtifactName(name) {
+    let n = String(name)
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\\/\x00-\x1f]/g, '_')
+        .replace(/\.{2,}/g, '_')
+        .trim();
+    if (!n || n === '.')
+        n = 'artifact';
+    if (n.length > 180) {
+        const ext = extname(n).slice(0, 16);
+        n = n.slice(0, 180 - ext.length) + ext;
+    }
+    return n;
+}
+/** Percent-encode the characters that would stop a URI segment from matching the
+ * swipium:// resource templates (`/`, `,`, space, `%`, `?`, `#`, non-ASCII…). Readable ids such as
+ * `feature:login` stay as-is; pair with decodeUriSegment on the read side. */
+export function encodeUriSegment(value) {
+    return value.replace(/[^A-Za-z0-9\-._~:@!$&'()*+;=]/gu, (c) => encodeURIComponent(c));
+}
+/** Inverse of encodeUriSegment; returns the input unchanged if it is not valid percent-encoding. */
+export function decodeUriSegment(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** Canonical form of a swipium:// URI for equality: every path segment decoded. */
+function canonicalUri(uri) {
+    return uri.split('/').map(decodeUriSegment).join('/');
+}
+/** True when `child` is `parent` or lies inside it (both resolved). */
+export function isWithinRoot(child, parent) {
+    const c = resolve(child);
+    const p = resolve(parent);
+    return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+/** Owner-only permissions for ~/.swipium/runs session data (dirs 0700, files 0600). POSIX only;
+ *  best-effort (a chmod failure never breaks a write). */
+export const PRIVATE_DIR_MODE = 0o700;
+export const PRIVATE_FILE_MODE = 0o600;
+function restrictFile(path) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        chmodSync(path, PRIVATE_FILE_MODE);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function mkdirPrivate(dir) {
+    mkdirSync(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+    if (process.platform === 'win32')
+        return;
+    try {
+        chmodSync(dir, PRIVATE_DIR_MODE); // mode above only applies to NEWLY created dirs (and umask)
+    }
+    catch {
+        /* best-effort */
+    }
+}
 function defaultSessionDir(root, id) {
     const projectHash = createHash('sha256').update(resolve(root)).digest('hex').slice(0, 16);
     return join(REGISTRY_DIR, 'runs', projectHash, id);
 }
+/** Trailing debounce for state.json writes (P2 write amplification): every mutator used to
+ * rewrite the full file synchronously. Correctness-critical writes (session creation, the
+ * mutation ledger, shutdown) still flush synchronously via persistNow()/flushAll(). */
+const PERSIST_DEBOUNCE_MS = 150;
 export class SessionStore {
     sessions = new Map();
-    constructor() {
+    // Lazy prior-session loading (P2 startup cost): the registry of up to 200 prior sessions is
+    // read on first access (get/list/find/create), not in the constructor.
+    registryLoaded = false;
+    dirty = new Set();
+    flushTimer;
+    // Sessions created or looked up by id in THIS process (see activeRoots).
+    activeIds = new Set();
+    ensureRegistryLoaded() {
+        if (this.registryLoaded)
+            return;
+        this.registryLoaded = true;
         this.loadRegistry();
+        // Retention (session/retention.ts): one non-blocking background prune of old ~/.swipium/runs
+        // session dirs per process, never a registered or live session. SWIPIUM_RETENTION_DAYS=off disables.
+        scheduleStartupPrune(() => [...this.sessions.values()].map((x) => x.dir));
     }
     create(root, budget, opts) {
+        this.ensureRegistryLoaded();
         const id = randomUUID().slice(0, 8);
         const dir = opts?.sessionDir ?? defaultSessionDir(root, id);
-        mkdirSync(dir, { recursive: true });
+        mkdirPrivate(dir);
         const now = Date.now();
         const s = {
-            id, root, dir, createdAt: now, screenshotCount: 0,
+            id,
+            root,
+            dir,
+            createdAt: now,
+            screenshotCount: 0,
             mode: 'structured',
             responseMode: opts?.responseMode ?? DEFAULT_RESPONSE_MODE,
             sensitive: opts?.sensitive ?? false,
             budget: { ...DEFAULT_BUDGET, ...(budget ?? {}) },
             counters: { actions: 0, screenshots: 0, snapshotFailures: 0, noChangeActions: 0 },
-            envChanges: [], workarounds: [],
-            jobs: new Map(), artifacts: [], findings: [], notes: [], mutations: [], recordedActions: [],
-            fixtures: opts?.fixtures ?? [], auth: {}, milestones: { session_start: now }, budgetProfile: opts?.budgetProfile,
-            secrets: new Set(), inputs: [], generatedValues: [], inputValues: new Map(), aborts: new Map(),
+            envChanges: [],
+            workarounds: [],
+            jobs: new Map(),
+            artifacts: [],
+            findings: [],
+            notes: [],
+            mutations: [],
+            recordedActions: [],
+            toolErrors: [],
+            fixtures: opts?.fixtures ?? [],
+            auth: {},
+            milestones: { session_start: now },
+            budgetProfile: opts?.budgetProfile,
+            secrets: new Set(),
+            inputs: [],
+            generatedValues: [],
+            inputValues: new Map(),
+            aborts: new Map(),
         };
         this.sessions.set(id, s);
+        this.activeIds.add(id);
         this.appendRegistry(id, dir);
-        this.persist(s);
+        this.persistNow(s); // synchronous: a concurrent instance / crash must see the new session
         return s;
     }
     get(id) {
-        return this.sessions.get(id);
+        this.ensureRegistryLoaded();
+        const s = this.sessions.get(id);
+        if (s)
+            this.activeIds.add(id);
+        return s;
     }
     list() {
+        this.ensureRegistryLoaded();
         return [...this.sessions.values()];
     }
+    /** Schedule a state.json write (trailing debounce). Mutators call this on every change;
+     * the actual write happens at most once per PERSIST_DEBOUNCE_MS per burst. Use
+     * persistNow()/flushAll() where a synchronous write is required for correctness. */
     persist(s) {
+        this.dirty.add(s);
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => this.flushDirty(), PERSIST_DEBOUNCE_MS);
+        this.flushTimer.unref?.(); // never keep the process alive just for a pending flush
+    }
+    /** Write this session's state.json immediately (and drop any pending debounce for it). */
+    persistNow(s) {
+        this.dirty.delete(s);
+        this.writeState(s);
+    }
+    /** Flush every dirty session synchronously. Called on shutdown / process exit so a graceful
+     * stop never loses debounced state. */
+    flushAll() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        for (const s of [...this.dirty]) {
+            this.dirty.delete(s);
+            this.writeState(s);
+        }
+    }
+    flushDirty() {
+        this.flushTimer = undefined;
+        for (const s of [...this.dirty]) {
+            this.dirty.delete(s);
+            this.writeState(s);
+        }
+    }
+    writeState(s) {
         try {
+            const safe = serializeSecretSafe(s); // registered secret values never reach state.json
+            // Keep the plain transport fields in sync with the live driver (duck-typed: no driver import),
+            // except while the live driver is a fallback for an unreachable WDA: the persisted 'wda'
+            // transport stays authoritative so a later restart retries it.
+            if (s.driver && !(s.transportFallback && s.driver.kind === 'simulator')) {
+                s.driverKind = s.driver.kind;
+                const baseUrl = s.driver.baseUrl;
+                if (s.driver.kind === 'wda' && typeof baseUrl === 'string')
+                    s.wdaUrl = baseUrl;
+            }
             const state = {
-                id: s.id, root: s.root, dir: s.dir, createdAt: s.createdAt,
-                device: s.device, appId: s.appId, headless: s.headless, metroPid: s.metroPid, screenshotCount: s.screenshotCount,
-                network: s.network, envChanges: s.envChanges, workarounds: s.workarounds,
-                mode: s.mode, responseMode: s.responseMode, sensitive: s.sensitive, budget: s.budget, counters: s.counters,
-                jobs: [...s.jobs.values()], artifacts: s.artifacts, findings: s.findings, notes: s.notes, mutations: s.mutations, recordedActions: s.recordedActions,
-                fixtures: s.fixtures, auth: s.auth, milestones: s.milestones, budgetProfile: s.budgetProfile,
-                inputs: s.inputs, // METADATA only — never the values
+                id: s.id,
+                root: s.root,
+                dir: s.dir,
+                createdAt: s.createdAt,
+                device: s.device,
+                driverKind: s.driverKind,
+                wdaUrl: s.wdaUrl,
+                appId: s.appId,
+                headless: s.headless,
+                metroPid: s.metroPid,
+                screenshotCount: s.screenshotCount,
+                network: s.network,
+                envChanges: safe.envChanges,
+                workarounds: s.workarounds,
+                chosenTarget: s.chosenTarget,
+                lastTestThisArgs: s.lastTestThisArgs && s.secrets.size ? redactDeep(s.lastTestThisArgs, makeRedactor(s.secrets)) : s.lastTestThisArgs,
+                mode: s.mode,
+                responseMode: s.responseMode,
+                sensitive: s.sensitive,
+                budget: s.budget,
+                counters: s.counters,
+                jobs: safe.jobs,
+                artifacts: s.artifacts,
+                findings: safe.findings,
+                notes: safe.notes,
+                mutations: safe.mutations,
+                recordedActions: safe.recordedActions,
+                toolErrors: safe.toolErrors,
+                fixtures: safe.fixtures,
+                auth: s.auth,
+                milestones: s.milestones,
+                budgetProfile: s.budgetProfile,
+                inputs: s.inputs, // METADATA only, never the values
                 generatedValues: serializeGeneratedValues(s.generatedValues), // secret raw values redacted before disk
                 exploration: s.exploration,
             };
-            writeFileSync(join(s.dir, 'state.json'), JSON.stringify(state, null, 2));
+            // Atomic write (tmp + rename) so a crash mid-write never leaves a truncated state.json.
+            const target = join(s.dir, 'state.json');
+            writeFileAtomicSync(target, JSON.stringify(state, null, 2));
+            restrictFile(target); // owner-only: state.json carries run history / paths
         }
-        catch {
-            /* best-effort */
+        catch (e) {
+            // A silent failure here means session state (jobs/artifacts/findings) is lost on restart.
+            log('error', 'failed to persist session state.json; this session will not survive a server restart', {
+                sessionId: s.id,
+                dir: s.dir,
+                err: String(e),
+            });
         }
     }
     // ---- jobs ----
@@ -123,6 +351,20 @@ export class SessionStore {
         s.mode = mode;
         this.persist(s);
     }
+    /**
+     * A structured UI dump just succeeded on this session: visual-fallback is per-screen, never
+     * permanent. Switch back to 'structured' and restart the consecutive-failure count. Returns
+     * true when the session was in visual-fallback (the caller may tell the agent it recovered).
+     */
+    noteStructuredDump(s) {
+        const recovered = s.mode === 'visual-fallback';
+        if (!recovered && s.counters.snapshotFailures === 0)
+            return false;
+        s.mode = 'structured';
+        s.counters.snapshotFailures = 0;
+        this.persist(s);
+        return recovered;
+    }
     bump(s, key, by = 1) {
         s.counters[key] += by;
         this.persist(s);
@@ -139,14 +381,14 @@ export class SessionStore {
         if (c.screenshots >= b.maxScreenshots)
             return `screenshot budget reached (${c.screenshots}/${b.maxScreenshots})`;
         if (c.noChangeActions >= b.maxNoChangeActions)
-            return `repeated no-change actions (${c.noChangeActions}/${b.maxNoChangeActions}) — likely wrong coords / disabled element / auth wall`;
+            return `repeated no-change actions (${c.noChangeActions}/${b.maxNoChangeActions}): likely wrong coords / disabled element / auth wall`;
         return null;
     }
     updateJob(s, job, patch) {
         Object.assign(job, patch);
         this.persist(s);
     }
-    /** Apply a patch ONLY while the job is still running — so a cancelled (or otherwise
+    /** Apply a patch ONLY while the job is still running, so a cancelled (or otherwise
      *  terminal) job is never overwritten back to done/failed by a racing worker. */
     updateJobIfRunning(s, job, patch) {
         const cur = s.jobs.get(job.jobId);
@@ -175,7 +417,7 @@ export class SessionStore {
         s.envChanges.push(`${new Date().toISOString()} ${note}`);
         this.persist(s);
     }
-    /** Record a safe fallback Swipium chose (roadmap §11 "workarounds attempted"). De-duped. */
+    /** Record a safe fallback Swipium chose. De-duped. */
     addWorkaround(s, note) {
         if (!s.workarounds.includes(note)) {
             s.workarounds.push(note);
@@ -187,15 +429,43 @@ export class SessionStore {
         this.persist(s);
     }
     recordMutation(s, mutation) {
-        const rec = { id: randomUUID().slice(0, 8), at: Date.now(), ...mutation };
+        // Audit trail (THREAT_MODEL): stamp HOW a consented action was approved (elicitation vs
+        // client re-call assertion) from the consent module, so every call site gets it for free.
+        let consent = mutation.consent;
+        if (consent?.approved && consent.consentId && !consent.approvalMechanism) {
+            const mechanism = approvalMechanismFor(consent.consentId);
+            if (mechanism)
+                consent = { ...consent, approvalMechanism: mechanism };
+        }
+        const rec = { id: randomUUID().slice(0, 8), at: Date.now(), ...mutation, ...(consent ? { consent } : {}) };
         s.mutations.push(rec);
         if (s.mutations.length > 500)
             s.mutations.splice(0, s.mutations.length - 500);
-        this.persist(s);
+        this.persistNow(s); // the mutation ledger is an audit trail; never leave it debounce-only
         return rec;
     }
-    /** Append an action-IR step (bounded) for qa_flow_generate. */
+    /** Record a tool call that returned an error for this session (bounded to the last 200). */
+    recordToolError(s, rec) {
+        if (rec.failureCode === 'CANCELLED')
+            return; // cancelled work is not a tool error
+        const list = (s.toolErrors ??= []);
+        list.push({ at: rec.at ?? Date.now(), tool: rec.tool, failureCode: rec.failureCode, message: rec.message.slice(0, 500) });
+        if (list.length > 200)
+            list.splice(0, list.length - 200);
+        this.persist(s);
+    }
+    /** Append an action-IR step (bounded) for qa_generate target:"flow". */
     addRecordedAction(s, ra) {
+        // Typed text equal to a stored session input (e.g. the email from qa_continue_from_blocker) is
+        // recorded as that input's ${VAR} placeholder, never the literal (generators do this too).
+        const bound = ra.action === 'type' ? inputPlaceholderFor(ra.text, inputBindings(s)) : undefined;
+        if (bound) {
+            ra = {
+                ...ra,
+                text: `\${${swipiumVarName(bound.varName)}}`,
+                ...(bound.secret ? { secret: true, exportability: 'needs-human-data' } : {}),
+            };
+        }
         s.recordedActions.push(ra);
         if (s.recordedActions.length > 300)
             s.recordedActions.splice(0, s.recordedActions.length - 300);
@@ -221,7 +491,9 @@ export class SessionStore {
         this.persist(s);
     }
     /** Store a user-provided input (hardening P0.5). The VALUE stays in-memory only; secrets are
-     *  added to the redaction set. Persists metadata so reports can say it was provided. */
+     *  added to the redaction set. Persists metadata so reports can say it was provided.
+     *  Secrets of 3+ characters are redacted (short ones as whole tokens); 1-2 character values are
+     *  not matched and are reported as partial redaction (src/lib/redact.ts). */
     setInput(s, varName, value, secret, source) {
         s.inputValues.set(varName, value);
         if (secret)
@@ -237,7 +509,7 @@ export class SessionStore {
         }
         this.persist(s);
     }
-    /** Variable map (varName → value) for the flow runner. In-memory values only. */
+    /** Variable map (varName > value) for the flow runner. In-memory values only. */
     inputVariables(s) {
         return Object.fromEntries(s.inputValues);
     }
@@ -245,33 +517,86 @@ export class SessionStore {
     clearInputValues(s) {
         s.inputValues.clear();
     }
+    /** Remember the ORIGINAL qa_test_this arguments (goal, goalText, flags) of this session's run. */
+    setLastTestThisArgs(s, args) {
+        s.lastTestThisArgs = { ...args, at: args.at ?? Date.now() };
+        this.persist(s);
+    }
     /** Record the latest guided-exploration result (Phase 3.3) for qa_report. */
     setExploration(s, rec) {
         s.exploration = rec;
         this.persist(s);
     }
     saveArtifact(s, kind, name, data, mime, label) {
+        // B5: never trust kind/name as path components. Sanitize, then verify containment.
+        kind = safeArtifactName(kind);
+        name = safeArtifactName(name);
         const sub = join(s.dir, artifactDirectoryName(kind));
-        mkdirSync(sub, { recursive: true });
         const path = join(sub, name);
+        if (!isWithinRoot(path, s.dir) || resolve(path) === resolve(s.dir)) {
+            throw new Error(`Refusing to write artifact outside the session directory: ${kind}/${name}`);
+        }
+        mkdirPrivate(sub);
         const redact = makeRedactor(s.secrets);
-        const storedData = typeof data === 'string' && isTextArtifactMime(mime) ? (redact(data) ?? '') : data;
+        const isRedactableText = typeof data === 'string' && isTextArtifactMime(mime);
+        // JSON/XML artifacts are redacted structurally (string values / attribute values / text
+        // nodes only) so a short numeric secret (CVV "123") can never rewrite `{"actions":123}`.
+        const storedData = isRedactableText ? redactStructuredText(data, structuredKindOf(mime, name), redact) : data;
         const storedLabel = label ? redact(label) : label;
-        writeFileSync(path, storedData);
-        const uri = `swipium://session/${s.id}/${kind}/${name}`;
-        s.artifacts.push({ uri, path, mime, kind, createdAt: Date.now(), label: storedLabel });
+        const skipped = redact.skippedShortSecrets ?? 0;
+        writeFileSync(path, storedData, { mode: PRIVATE_FILE_MODE });
+        restrictFile(path); // an overwritten artifact keeps its old mode otherwise
+        const uri = `swipium://session/${encodeUriSegment(s.id)}/${encodeUriSegment(kind)}/${encodeUriSegment(name)}`;
+        // Binary artifacts (screenshots/recordings) cannot be redacted, so tag them explicitly so
+        // consumers (qa_get_artifact, reports) know pixels may show sensitive on-screen content.
+        s.artifacts.push({
+            uri,
+            path,
+            mime,
+            kind,
+            createdAt: Date.now(),
+            label: storedLabel,
+            redaction: !isRedactableText ? 'not-applied' : skipped > 0 ? 'partial' : 'applied',
+            ...(isRedactableText && skipped > 0
+                ? {
+                    redactionNote: `${skipped} secret value(s) shorter than 3 characters were not redacted (matching them would corrupt ordinary text).`,
+                }
+                : {}),
+        });
         this.persist(s);
         return uri;
     }
     findArtifact(uri) {
+        this.ensureRegistryLoaded();
         for (const s of this.sessions.values()) {
             const rec = s.artifacts.find((a) => a.uri === uri);
             if (rec)
                 return { session: s, rec };
         }
+        // Encoding-insensitive fallback: a client (or URL normalisation) may percent-encode a URI
+        // that was stored raw (pre-1.6 records), or vice versa.
+        const want = canonicalUri(uri);
+        for (const s of this.sessions.values()) {
+            const rec = s.artifacts.find((a) => canonicalUri(a.uri) === want);
+            if (rec)
+                return { session: s, rec };
+        }
         return undefined;
     }
-    // ---- persistence reload ----
+    /** Project roots this server process is actively working on: roots of sessions created here
+     * or touched by a tool call (get) since start, NOT every prior session reloaded from the
+     * machine-wide registry. Used to scope resources/list to the current project(s). */
+    activeRoots() {
+        this.ensureRegistryLoaded();
+        const roots = new Set();
+        for (const id of this.activeIds) {
+            const s = this.sessions.get(id);
+            if (s)
+                roots.add(s.root);
+        }
+        return [...roots];
+    }
+    // ---- persistence reload (lazy, triggered by the first get/list/find/create) ----
     loadRegistry() {
         try {
             if (!existsSync(REGISTRY))
@@ -283,6 +608,9 @@ export class SessionStore {
                     continue;
                 try {
                     const st = JSON.parse(readFileSync(sp, 'utf8'));
+                    // Never clobber a LIVE session created by this process (lazy load can run after create()).
+                    if (typeof st.id === 'string' && this.sessions.has(st.id))
+                        continue;
                     const jobs = new Map((st.jobs ?? []).map((j) => [j.jobId, j]));
                     for (const j of jobs.values()) {
                         if (j.status === 'running') {
@@ -290,39 +618,111 @@ export class SessionStore {
                             j.error = 'server restarted while job was running (child process gone)';
                         }
                     }
+                    // Orphaned-process handling: a prior server persisted its Metro pid. If no live
+                    // server instance owns that pid, reclaimPid (processRegistry) reaps it ONLY when the
+                    // registry's recorded fingerprint (start time + full command) still matches. A
+                    // recycled or unverifiable pid is never signalled, and a process group is signalled
+                    // only when Swipium spawned the child as a group leader. Either way the reloaded
+                    // session drops the pid: it is not ours to manage (or stop) anymore.
+                    if (typeof st.metroPid === 'number' && st.metroPid > 0) {
+                        if (!pidOwnedByLiveServer(st.metroPid)) {
+                            const outcome = reclaimPid(st.metroPid, 'metro');
+                            if (outcome === 'killed')
+                                log('warn', 'reaped orphaned Metro bundler from a previous server run', { pid: st.metroPid, sessionId: st.id });
+                        }
+                        st.metroPid = undefined; // reaped, gone, recycled, or another live server's; never ours
+                    }
+                    // Raw secret values never touch disk, so a rehydrated session cannot rebuild
+                    // its redaction set. If the persisted state shows prior secret-bearing activity
+                    // (secret inputs, secret generated values, or a performed login), flag the session so
+                    // qa_report discloses that artifacts written after the restart are no longer scrubbed.
+                    const priorSecrets = (st.inputs ?? []).some((i) => i.secret) ||
+                        (st.generatedValues ?? []).some((g) => g.secret) ||
+                        st.auth?.loginPerformed === true;
                     const s = {
-                        id: st.id, root: st.root, dir: st.dir, createdAt: st.createdAt,
-                        device: st.device, appId: st.appId, headless: st.headless, metroPid: st.metroPid, screenshotCount: st.screenshotCount ?? 0,
-                        network: st.network, envChanges: st.envChanges ?? [], workarounds: st.workarounds ?? [],
+                        id: st.id,
+                        root: st.root,
+                        dir: st.dir,
+                        createdAt: st.createdAt,
+                        device: st.device,
+                        appId: st.appId,
+                        headless: st.headless,
+                        metroPid: st.metroPid,
+                        screenshotCount: st.screenshotCount ?? 0,
+                        network: st.network,
+                        envChanges: st.envChanges ?? [],
+                        workarounds: st.workarounds ?? [],
+                        chosenTarget: typeof st.chosenTarget === 'string' ? st.chosenTarget : undefined,
+                        lastTestThisArgs: st.lastTestThisArgs && typeof st.lastTestThisArgs === 'object' && !Array.isArray(st.lastTestThisArgs)
+                            ? st.lastTestThisArgs
+                            : undefined,
                         mode: st.mode ?? 'structured',
                         responseMode: st.responseMode ?? DEFAULT_RESPONSE_MODE,
                         sensitive: st.sensitive ?? false,
                         budget: { ...DEFAULT_BUDGET, ...(st.budget ?? {}) },
                         counters: { actions: 0, screenshots: 0, snapshotFailures: 0, noChangeActions: 0, ...(st.counters ?? {}) },
-                        jobs, artifacts: st.artifacts ?? [], findings: st.findings ?? [], notes: st.notes ?? [], mutations: st.mutations ?? [], recordedActions: st.recordedActions ?? [],
-                        fixtures: st.fixtures ?? [], auth: st.auth ?? {}, milestones: st.milestones ?? { session_start: st.createdAt }, budgetProfile: st.budgetProfile,
-                        secrets: new Set(), inputs: st.inputs ?? [], generatedValues: st.generatedValues ?? [], inputValues: new Map(), exploration: st.exploration, aborts: new Map(),
+                        jobs,
+                        artifacts: st.artifacts ?? [],
+                        findings: st.findings ?? [],
+                        notes: st.notes ?? [],
+                        mutations: st.mutations ?? [],
+                        recordedActions: st.recordedActions ?? [],
+                        toolErrors: st.toolErrors ?? [],
+                        driverKind: typeof st.driverKind === 'string' ? st.driverKind : undefined,
+                        wdaUrl: typeof st.wdaUrl === 'string' ? st.wdaUrl : undefined,
+                        // Live fixture values come from the project's fixtures.json (+ SWIPIUM_* env at use),
+                        // never from state.json, which only holds value-less metadata.
+                        fixtures: rehydrateFixtures(st.root, st.fixtures),
+                        auth: st.auth ?? {},
+                        milestones: st.milestones ?? { session_start: st.createdAt },
+                        budgetProfile: st.budgetProfile,
+                        secrets: new Set(),
+                        redactionDegraded: priorSecrets || undefined,
+                        inputs: st.inputs ?? [],
+                        generatedValues: st.generatedValues ?? [],
+                        inputValues: new Map(),
+                        exploration: st.exploration,
+                        aborts: new Map(),
                     };
                     this.sessions.set(s.id, s);
                 }
-                catch {
-                    /* skip a corrupt session */
+                catch (e) {
+                    // Skip a corrupt session, but say so, otherwise prior artifacts/reports vanish silently.
+                    log('warn', 'skipping corrupt prior session state.json on reload', { dir, err: String(e) });
                 }
             }
         }
-        catch {
-            /* no registry */
+        catch (e) {
+            log('warn', 'session registry unreadable, prior sessions will not be reloaded', { registry: REGISTRY, err: String(e) });
         }
     }
+    /** Append this session to the shared ~/.swipium/registry.json. Guarded by an advisory
+     * lockfile + atomic rename so two concurrent server instances (common with multiple MCP
+     * clients) never clobber each other's read-modify-write. */
     appendRegistry(id, dir) {
         try {
             mkdirSync(REGISTRY_DIR, { recursive: true });
-            const reg = existsSync(REGISTRY) ? JSON.parse(readFileSync(REGISTRY, 'utf8')) : [];
-            reg.push({ id, dir });
-            writeFileSync(REGISTRY, JSON.stringify(reg.slice(-200), null, 2));
+            withFileLock(`${REGISTRY}.lock`, () => {
+                let reg = [];
+                if (existsSync(REGISTRY)) {
+                    try {
+                        const parsed = JSON.parse(readFileSync(REGISTRY, 'utf8'));
+                        if (Array.isArray(parsed))
+                            reg = parsed;
+                    }
+                    catch (e) {
+                        log('warn', 'registry.json corrupt, rebuilding it (prior sessions may need re-registration)', {
+                            registry: REGISTRY,
+                            err: String(e),
+                        });
+                    }
+                }
+                reg.push({ id, dir });
+                writeFileAtomicSync(REGISTRY, JSON.stringify(reg.slice(-200), null, 2)); // atomic on the same filesystem
+            });
         }
-        catch {
-            /* best-effort */
+        catch (e) {
+            log('error', 'failed to append session to registry; it will not be reloadable after a restart', { id, dir, err: String(e) });
         }
     }
 }