reflectt-node 0.1.0

package/dist/service-probe.d.ts

@@ -0,0 +1,53 @@
+interface ProbeConfig {
+    /** Base URL of the reflectt-node service */
+    baseUrl: string;
+    /** Probe interval in seconds */
+    intervalSec: number;
+    /** Timeout per endpoint check in ms */
+    timeoutMs: number;
+    /** Consecutive failures before restart */
+    maxRetries: number;
+    /** Backoff multiplier for restart attempts */
+    backoffMultiplier: number;
+    /** Maximum restarts before giving up (per hour) */
+    maxRestartsPerHour: number;
+    /** Dry run: log but don't restart */
+    dryRun: boolean;
+    /** Log file path */
+    logPath: string;
+    /** LaunchAgent label for restart */
+    launchAgentLabel: string;
+}
+declare const DEFAULT_CONFIG: ProbeConfig;
+interface EndpointCheck {
+    name: string;
+    path: string;
+    /** Validate the response body */
+    validate: (body: unknown) => boolean;
+    /** If true, failure of this endpoint alone triggers restart */
+    critical: boolean;
+}
+declare const ENDPOINTS: EndpointCheck[];
+interface ProbeState {
+    consecutiveFailures: number;
+    restartTimestamps: number[];
+    lastCheckAt: number | null;
+    lastSuccessAt: number | null;
+    totalChecks: number;
+    totalFailures: number;
+    totalRestarts: number;
+}
+declare const state: ProbeState;
+declare function checkEndpoint(config: ProbeConfig, endpoint: EndpointCheck): Promise<{
+    ok: boolean;
+    latencyMs: number;
+    error?: string;
+}>;
+declare function canRestart(config: ProbeConfig): {
+    allowed: boolean;
+    reason?: string;
+};
+declare function triggerRestart(config: ProbeConfig, reason: string): boolean;
+declare function runProbe(config: ProbeConfig): Promise<void>;
+export { checkEndpoint, runProbe, triggerRestart, canRestart, state as _probeState, ENDPOINTS, DEFAULT_CONFIG, type ProbeConfig, type ProbeState, type EndpointCheck, };
+//# sourceMappingURL=service-probe.d.ts.map

package/dist/service-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-probe.d.ts","sourceRoot":"","sources":["../src/service-probe.ts"],"names":[],"mappings":"AAcA,UAAU,WAAW;IACnB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;IACf,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAA;IACjB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,iBAAiB,EAAE,MAAM,CAAA;IACzB,mDAAmD;IACnD,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAA;IACf,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,QAAA,MAAM,cAAc,EAAE,WAUrB,CAAA;AAID,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAA;IACpC,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,QAAA,MAAM,SAAS,EAAE,aAAa,EA4B7B,CAAA;AAID,UAAU,UAAU;IAClB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,QAAA,MAAM,KAAK,EAAE,UAQZ,CAAA;AAiBD,iBAAe,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0BtI;AAID,iBAAS,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAY9E;AAED,iBAAS,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAgCpE;AAID,iBAAe,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwC1D;AA0DD,OAAO,EACL,aAAa,EACb,QAAQ,EACR,cAAc,EACd,UAAU,EACV,KAAK,IAAI,WAAW,EACpB,SAAS,EACT,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,CAAA"}

package/dist/service-probe.js

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: Apache-2.0
+// Synthetic health probe for reflectt-node service.
+//
+// Periodically validates critical endpoints and triggers auto-restart
+// on sustained failure. Runs as a standalone process (not inside the server).
+//
+// Usage: node dist/service-probe.js [--interval 30] [--max-retries 3] [--dry-run]
+import { execSync } from 'node:child_process';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const DEFAULT_CONFIG = {
+    baseUrl: 'http://127.0.0.1:4445',
+    intervalSec: 30,
+    timeoutMs: 5000,
+    maxRetries: 3,
+    backoffMultiplier: 2,
+    maxRestartsPerHour: 5,
+    dryRun: false,
+    logPath: 'logs/service-probe.log',
+    launchAgentLabel: 'com.reflectt.node',
+};
+const ENDPOINTS = [
+    {
+        name: 'health',
+        path: '/health',
+        validate: (body) => {
+            const b = body;
+            return b?.status === 'ok';
+        },
+        critical: true,
+    },
+    {
+        name: 'tasks-list',
+        path: '/tasks?limit=1',
+        validate: (body) => {
+            const b = body;
+            return b?.success === true || Array.isArray(b?.tasks);
+        },
+        critical: true,
+    },
+    {
+        name: 'noise-budget',
+        path: '/chat/noise-budget',
+        validate: (body) => {
+            const b = body;
+            return b?.success === true;
+        },
+        critical: false,
+    },
+];
+const state = {
+    consecutiveFailures: 0,
+    restartTimestamps: [],
+    lastCheckAt: null,
+    lastSuccessAt: null,
+    totalChecks: 0,
+    totalFailures: 0,
+    totalRestarts: 0,
+};
+// ── Logging ──
+async function log(level, message, extra) {
+    const ts = new Date().toISOString();
+    const line = JSON.stringify({ ts, level, message, ...extra });
+    console.log(`[${level}] ${message}`);
+    try {
+        await mkdir(dirname(DEFAULT_CONFIG.logPath), { recursive: true });
+        await appendFile(DEFAULT_CONFIG.logPath, line + '\n');
+    }
+    catch { /* ignore log write failures */ }
+}
+// ── HTTP Check ──
+async function checkEndpoint(config, endpoint) {
+    const url = `${config.baseUrl}${endpoint.path}`;
+    const start = Date.now();
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+        const res = await fetch(url, { signal: controller.signal });
+        clearTimeout(timer);
+        const latencyMs = Date.now() - start;
+        if (!res.ok) {
+            return { ok: false, latencyMs, error: `HTTP ${res.status}` };
+        }
+        const body = await res.json();
+        const valid = endpoint.validate(body);
+        return { ok: valid, latencyMs, error: valid ? undefined : 'validation failed' };
+    }
+    catch (err) {
+        const latencyMs = Date.now() - start;
+        const error = err instanceof Error ? err.message : String(err);
+        return { ok: false, latencyMs, error };
+    }
+}
+// ── Restart Logic ──
+function canRestart(config) {
+    const now = Date.now();
+    const hourAgo = now - 3600_000;
+    // Prune old timestamps
+    state.restartTimestamps = state.restartTimestamps.filter(ts => ts > hourAgo);
+    if (state.restartTimestamps.length >= config.maxRestartsPerHour) {
+        return { allowed: false, reason: `Max restarts/hour (${config.maxRestartsPerHour}) reached` };
+    }
+    return { allowed: true };
+}
+function triggerRestart(config, reason) {
+    const { allowed, reason: denyReason } = canRestart(config);
+    if (!allowed) {
+        log('ERROR', `Restart denied: ${denyReason}`, { reason, restartCount: state.totalRestarts });
+        return false;
+    }
+    if (config.dryRun) {
+        log('WARN', `[DRY-RUN] Would restart: ${reason}`);
+        return false;
+    }
+    try {
+        log('ALERT', `Restarting service: ${reason}`, {
+            consecutiveFailures: state.consecutiveFailures,
+            restartCount: state.totalRestarts + 1,
+        });
+        const uid = execSync('id -u').toString().trim();
+        execSync(`launchctl kickstart -k gui/${uid}/${config.launchAgentLabel}`, { timeout: 10000 });
+        state.restartTimestamps.push(Date.now());
+        state.totalRestarts++;
+        state.consecutiveFailures = 0;
+        return true;
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        log('ERROR', `Restart failed: ${error}`, { reason });
+        return false;
+    }
+}
+// ── Probe Cycle ──
+async function runProbe(config) {
+    state.totalChecks++;
+    state.lastCheckAt = Date.now();
+    const results = [];
+    for (const endpoint of ENDPOINTS) {
+        const result = await checkEndpoint(config, endpoint);
+        results.push({ endpoint: endpoint.name, ...result, critical: endpoint.critical });
+    }
+    const criticalFailures = results.filter(r => !r.ok && r.critical);
+    const allOk = results.every(r => r.ok);
+    if (allOk) {
+        state.consecutiveFailures = 0;
+        state.lastSuccessAt = Date.now();
+        // Only log every 10th success to reduce noise
+        if (state.totalChecks % 10 === 0) {
+            await log('INFO', 'Probe OK', {
+                latencies: Object.fromEntries(results.map(r => [r.endpoint, r.latencyMs])),
+                totalChecks: state.totalChecks,
+            });
+        }
+    }
+    else {
+        state.consecutiveFailures++;
+        state.totalFailures++;
+        await log('WARN', `Probe failed (${state.consecutiveFailures}/${config.maxRetries})`, {
+            failures: results.filter(r => !r.ok).map(r => ({ endpoint: r.endpoint, error: r.error, latencyMs: r.latencyMs })),
+            critical: criticalFailures.length > 0,
+        });
+        if (criticalFailures.length > 0 && state.consecutiveFailures >= config.maxRetries) {
+            const failedNames = criticalFailures.map(f => f.endpoint).join(', ');
+            const errors = criticalFailures.map(f => `${f.endpoint}: ${f.error}`).join('; ');
+            triggerRestart(config, `${state.consecutiveFailures} consecutive critical failures on [${failedNames}]: ${errors}`);
+        }
+    }
+}
+// ── Main ──
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const config = {};
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--interval':
+                config.intervalSec = Number(args[++i]);
+                break;
+            case '--max-retries':
+                config.maxRetries = Number(args[++i]);
+                break;
+            case '--timeout':
+                config.timeoutMs = Number(args[++i]);
+                break;
+            case '--dry-run':
+                config.dryRun = true;
+                break;
+            case '--base-url':
+                config.baseUrl = args[++i];
+                break;
+            case '--log':
+                config.logPath = args[++i];
+                break;
+        }
+    }
+    return config;
+}
+async function main() {
+    const overrides = parseArgs();
+    const config = { ...DEFAULT_CONFIG, ...overrides };
+    await log('INFO', 'Service probe starting', {
+        interval: config.intervalSec,
+        maxRetries: config.maxRetries,
+        timeout: config.timeoutMs,
+        dryRun: config.dryRun,
+        endpoints: ENDPOINTS.map(e => e.name),
+    });
+    // Run immediately, then on interval
+    await runProbe(config);
+    setInterval(() => {
+        runProbe(config).catch(err => {
+            console.error('[ServiceProbe] Unexpected error:', err);
+        });
+    }, config.intervalSec * 1000);
+}
+// ── Exported for testing ──
+export { checkEndpoint, runProbe, triggerRestart, canRestart, state as _probeState, ENDPOINTS, DEFAULT_CONFIG, };
+// Run if executed directly
+const isMain = process.argv[1]?.endsWith('service-probe.js') || process.argv[1]?.endsWith('service-probe.ts');
+if (isMain) {
+    main().catch(err => {
+        console.error('Fatal:', err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=service-probe.js.map

package/dist/service-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-probe.js","sourceRoot":"","sources":["../src/service-probe.ts"],"names":[],"mappings":"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"}

package/dist/shared-workspace-api.d.ts

@@ -0,0 +1,73 @@
+export declare const ALLOWED_EXTENSIONS: Set<string>;
+export interface SharedFileEntry {
+    name: string;
+    path: string;
+    type: 'file' | 'directory';
+    size?: number;
+    extension?: string;
+}
+export interface SharedFileContent {
+    path: string;
+    content: string;
+    size: number;
+    truncated: boolean;
+    source: 'shared-workspace';
+}
+export interface SharedListResult {
+    success: boolean;
+    root: string;
+    path: string;
+    entries: SharedFileEntry[];
+    error?: string;
+}
+export interface SharedReadResult {
+    success: boolean;
+    file?: SharedFileContent;
+    error?: string;
+}
+/**
+ * Validate a relative path against security invariants.
+ * Returns the resolved absolute path or throws.
+ *
+ * This is a synchronous pre-check. For full security (symlink containment),
+ * use validatePathWithRealpath() which also resolves symlinks.
+ */
+export declare function validatePath(relPath: string): string;
+/**
+ * Validate path AND resolve symlinks for full containment check.
+ * Prevents symlink escape attacks (e.g., a symlinked dir inside process/ pointing outside root).
+ *
+ * On macOS, realpath handles APFS case-insensitivity and /var→/private/var canonicalization.
+ */
+export declare function validatePathWithRealpath(relPath: string): Promise<string>;
+/**
+ * Validate file extension against allowlist.
+ */
+export declare function validateExtension(filePath: string): void;
+/**
+ * List files in a shared workspace directory.
+ * Uses lstat to detect symlinks; verifies symlink targets stay within root.
+ */
+export declare function listSharedFiles(relPath?: string, limit?: number): Promise<SharedListResult>;
+/**
+ * Read a file from the shared workspace.
+ * Returns content (truncated to MAX_FILE_SIZE) or preview (first N chars).
+ * Uses realpath containment to defeat symlink escape attacks.
+ */
+export declare function readSharedFile(relPath: string, opts?: {
+    preview?: boolean;
+    maxChars?: number;
+}): Promise<SharedReadResult>;
+/**
+ * Resolve a task artifact path: try workspace root first, then shared workspace fallback.
+ * Uses realpath containment for shared workspace paths.
+ * Returns metadata about accessibility.
+ */
+export declare function resolveTaskArtifact(artifactPath: string, workspaceRoot: string): Promise<{
+    type: 'file' | 'directory' | 'missing';
+    accessible: boolean;
+    source: 'workspace' | 'shared-workspace' | null;
+    resolvedPath: string | null;
+    preview?: string;
+}>;
+//# sourceMappingURL=shared-workspace-api.d.ts.map

package/dist/shared-workspace-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-workspace-api.d.ts","sourceRoot":"","sources":["../src/shared-workspace-api.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,kBAAkB,aAA6D,CAAA;AAK5F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,kBAAkB,CAAA;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,iBAAiB,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgCpD;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B/E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAKxD;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,MAAmB,EAAE,KAAK,GAAE,MAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2ElH;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAA;IACtC,UAAU,EAAE,OAAO,CAAA;IACnB,MAAM,EAAE,WAAW,GAAG,kBAAkB,GAAG,IAAI,CAAA;IAC/C,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAC,CAwED"}

package/dist/shared-workspace-api.js

@@ -0,0 +1,281 @@
+// SPDX-License-Identifier: Apache-2.0
+// Shared workspace read API — safe, read-only access to shared artifacts.
+//
+// Security invariants:
+// - Only repo-relative paths (no absolute, no drive letters)
+// - Normalize + reject any '..' segments
+// - Allowlist prefixes: process/ (extensible)
+// - realpath containment: resolved real path must be under shared root (defeats symlink escape)
+// - Extension allowlist: .md, .txt, .json, .log, .yml, .yaml
+// - Size cap: 400KB
+// - Listing uses lstat to detect symlinks; symlinks pointing outside root are skipped
+//
+// Note: we do NOT try to model host-credential scoped access here. Access is gated
+// at the API route layer (localhost only for reflectt-node).
+import { promises as fs } from 'fs';
+import { resolve, extname, normalize, relative, isAbsolute } from 'path';
+import { SHARED_WORKSPACE } from './artifact-mirror.js';
+const ALLOWED_PREFIXES = ['process/'];
+export const ALLOWED_EXTENSIONS = new Set(['.md', '.txt', '.json', '.log', '.yml', '.yaml']);
+const MAX_FILE_SIZE = 400 * 1024; // 400KB
+const MAX_PREVIEW_CHARS = 2000;
+const MAX_LIST_ENTRIES = 500;
+/**
+ * Validate a relative path against security invariants.
+ * Returns the resolved absolute path or throws.
+ *
+ * This is a synchronous pre-check. For full security (symlink containment),
+ * use validatePathWithRealpath() which also resolves symlinks.
+ */
+export function validatePath(relPath) {
+    if (!relPath || typeof relPath !== 'string') {
+        throw new Error('Path is required');
+    }
+    // Reject absolute paths / drive letters
+    if (isAbsolute(relPath) || /^[A-Za-z]:/.test(relPath)) {
+        throw new Error('Absolute paths are not allowed');
+    }
+    // Reject .. segments (before normalization to prevent bypass)
+    if (relPath.includes('..')) {
+        throw new Error('Path traversal (..) is not allowed');
+    }
+    // Check prefix allowlist
+    const normalized = normalize(relPath).replace(/\\/g, '/');
+    if (!ALLOWED_PREFIXES.some(prefix => normalized.startsWith(prefix))) {
+        throw new Error(`Path must start with one of: ${ALLOWED_PREFIXES.join(', ')}`);
+    }
+    // Resolve against shared workspace root
+    const sharedRoot = SHARED_WORKSPACE();
+    const resolved = resolve(sharedRoot, relPath);
+    // Containment check via path.relative (not string prefix — avoids /root vs /root-evil confusion)
+    const rel = relative(sharedRoot, resolved);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error('Path escapes shared workspace root');
+    }
+    return resolved;
+}
+/**
+ * Validate path AND resolve symlinks for full containment check.
+ * Prevents symlink escape attacks (e.g., a symlinked dir inside process/ pointing outside root).
+ *
+ * On macOS, realpath handles APFS case-insensitivity and /var→/private/var canonicalization.
+ */
+export async function validatePathWithRealpath(relPath) {
+    // Run synchronous checks first
+    const resolved = validatePath(relPath);
+    // Get real paths (resolves symlinks)
+    const sharedRoot = SHARED_WORKSPACE();
+    let rootReal;
+    try {
+        rootReal = await fs.realpath(sharedRoot);
+    }
+    catch {
+        throw new Error('Shared workspace root does not exist or is inaccessible');
+    }
+    let candidateReal;
+    try {
+        candidateReal = await fs.realpath(resolved);
+    }
+    catch {
+        // File doesn't exist yet — the synchronous check already validated structure
+        throw new Error('Path does not exist');
+    }
+    // Containment via path.relative on real paths
+    const rel = relative(rootReal, candidateReal);
+    if (rel === '')
+        return candidateReal; // candidate IS root (for listing)
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error('Path escapes shared workspace root (symlink escape detected)');
+    }
+    return candidateReal;
+}
+/**
+ * Validate file extension against allowlist.
+ */
+export function validateExtension(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    if (!ALLOWED_EXTENSIONS.has(ext)) {
+        throw new Error(`File extension '${ext}' is not allowed. Allowed: ${[...ALLOWED_EXTENSIONS].join(', ')}`);
+    }
+}
+/**
+ * List files in a shared workspace directory.
+ * Uses lstat to detect symlinks; verifies symlink targets stay within root.
+ */
+export async function listSharedFiles(relPath = 'process/', limit = 200) {
+    try {
+        const realResolved = await validatePathWithRealpath(relPath);
+        const sharedRoot = SHARED_WORKSPACE();
+        let rootReal;
+        try {
+            rootReal = await fs.realpath(sharedRoot);
+        }
+        catch {
+            return { success: false, root: sharedRoot, path: relPath, entries: [], error: 'Shared workspace root inaccessible' };
+        }
+        const stat = await fs.lstat(realResolved);
+        if (!stat.isDirectory()) {
+            return { success: false, root: sharedRoot, path: relPath, entries: [], error: 'Path is not a directory' };
+        }
+        const rawEntries = await fs.readdir(realResolved, { withFileTypes: true });
+        const entries = [];
+        const effectiveLimit = Math.min(limit, MAX_LIST_ENTRIES);
+        for (const entry of rawEntries) {
+            if (entries.length >= effectiveLimit)
+                break;
+            const entryFullPath = resolve(realResolved, entry.name);
+            const entryRelPath = `${relPath.replace(/\/$/, '')}/${entry.name}`;
+            // Use lstat to detect symlinks
+            let entryStat;
+            try {
+                entryStat = await fs.lstat(entryFullPath);
+            }
+            catch {
+                continue; // skip inaccessible
+            }
+            // For symlinks: resolve and check containment
+            if (entryStat.isSymbolicLink()) {
+                try {
+                    const realTarget = await fs.realpath(entryFullPath);
+                    const rel = relative(rootReal, realTarget);
+                    if (rel.startsWith('..') || isAbsolute(rel)) {
+                        continue; // symlink escapes root — skip silently
+                    }
+                    entryStat = await fs.stat(realTarget);
+                }
+                catch {
+                    continue; // broken symlink — skip
+                }
+            }
+            if (entryStat.isDirectory()) {
+                entries.push({ name: entry.name, path: entryRelPath, type: 'directory' });
+            }
+            else if (entryStat.isFile()) {
+                const ext = extname(entry.name).toLowerCase();
+                if (!ALLOWED_EXTENSIONS.has(ext))
+                    continue; // skip disallowed extensions
+                entries.push({
+                    name: entry.name,
+                    path: entryRelPath,
+                    type: 'file',
+                    size: entryStat.size,
+                    extension: ext,
+                });
+            }
+        }
+        // Sort: directories first, then by name
+        entries.sort((a, b) => {
+            if (a.type !== b.type)
+                return a.type === 'directory' ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        return { success: true, root: sharedRoot, path: relPath, entries };
+    }
+    catch (err) {
+        return { success: false, root: SHARED_WORKSPACE(), path: relPath, entries: [], error: err.message };
+    }
+}
+/**
+ * Read a file from the shared workspace.
+ * Returns content (truncated to MAX_FILE_SIZE) or preview (first N chars).
+ * Uses realpath containment to defeat symlink escape attacks.
+ */
+export async function readSharedFile(relPath, opts) {
+    try {
+        const realResolved = await validatePathWithRealpath(relPath);
+        validateExtension(realResolved);
+        const stat = await fs.stat(realResolved);
+        if (!stat.isFile()) {
+            return { success: false, error: 'Path is not a file' };
+        }
+        if (stat.size > MAX_FILE_SIZE) {
+            return { success: false, error: `File exceeds size limit (${stat.size} bytes > ${MAX_FILE_SIZE} bytes)` };
+        }
+        const raw = await fs.readFile(realResolved, 'utf-8');
+        const maxChars = opts?.preview ? (opts.maxChars || MAX_PREVIEW_CHARS) : raw.length;
+        const content = raw.slice(0, maxChars);
+        return {
+            success: true,
+            file: {
+                path: relPath,
+                content,
+                size: stat.size,
+                truncated: content.length < raw.length,
+                source: 'shared-workspace',
+            },
+        };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/**
+ * Resolve a task artifact path: try workspace root first, then shared workspace fallback.
+ * Uses realpath containment for shared workspace paths.
+ * Returns metadata about accessibility.
+ */
+export async function resolveTaskArtifact(artifactPath, workspaceRoot) {
+    if (!artifactPath) {
+        return { type: 'missing', accessible: false, source: null, resolvedPath: null };
+    }
+    const trimmed = String(artifactPath).trim();
+    const normalizedPath = trimmed.startsWith('shared/') ? trimmed.slice('shared/'.length) : trimmed;
+    // Reject obviously unsafe paths early
+    if (isAbsolute(normalizedPath) || normalizedPath.includes('..') || normalizedPath.includes('\0')) {
+        return { type: 'missing', accessible: false, source: null, resolvedPath: null };
+    }
+    // Try workspace root first (repo-local)
+    const wsPath = resolve(workspaceRoot, normalizedPath);
+    // Containment check for workspace root too
+    const wsRel = relative(workspaceRoot, wsPath);
+    if (!wsRel.startsWith('..') && !isAbsolute(wsRel)) {
+        const wsStat = await fs.stat(wsPath).catch(() => null);
+        if (wsStat) {
+            const type = wsStat.isDirectory() ? 'directory' : 'file';
+            let preview;
+            if (type === 'file' && wsStat.size <= MAX_FILE_SIZE) {
+                const ext = extname(wsPath).toLowerCase();
+                if (ALLOWED_EXTENSIONS.has(ext)) {
+                    const raw = await fs.readFile(wsPath, 'utf-8').catch(() => '');
+                    preview = raw.slice(0, MAX_PREVIEW_CHARS);
+                }
+            }
+            return { type, accessible: true, source: 'workspace', resolvedPath: wsPath, preview };
+        }
+    }
+    // Fallback to shared workspace — locked down (prefix + extension allowlist)
+    // V1 safety: only allow shared fallback for process/* artifacts.
+    if (!normalizedPath.startsWith('process/')) {
+        return { type: 'missing', accessible: false, source: null, resolvedPath: null };
+    }
+    // Use the hardened shared-workspace validator (prefix allowlist + traversal + realpath containment).
+    let sharedReal;
+    try {
+        sharedReal = await validatePathWithRealpath(normalizedPath);
+    }
+    catch {
+        return { type: 'missing', accessible: false, source: null, resolvedPath: null };
+    }
+    const sharedStat = await fs.stat(sharedReal).catch(() => null);
+    if (sharedStat) {
+        const type = sharedStat.isDirectory() ? 'directory' : 'file';
+        // For files, enforce extension allowlist before exposing as accessible.
+        if (type === 'file') {
+            const ext = extname(sharedReal).toLowerCase();
+            if (!ALLOWED_EXTENSIONS.has(ext)) {
+                return { type: 'missing', accessible: false, source: null, resolvedPath: null };
+            }
+        }
+        let preview;
+        if (type === 'file' && sharedStat.size <= MAX_FILE_SIZE) {
+            const ext = extname(sharedReal).toLowerCase();
+            if (ALLOWED_EXTENSIONS.has(ext)) {
+                const raw = await fs.readFile(sharedReal, 'utf-8').catch(() => '');
+                preview = raw.slice(0, MAX_PREVIEW_CHARS);
+            }
+        }
+        return { type, accessible: true, source: 'shared-workspace', resolvedPath: sharedReal, preview };
+    }
+    return { type: 'missing', accessible: false, source: null, resolvedPath: null };
+}
+//# sourceMappingURL=shared-workspace-api.js.map