@deksden-com/dd-flow-cli 0.1.0

package/dist/services/lanes.js

@@ -0,0 +1,327 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+const defaultTtlSeconds = 300;
+const defaultPollIntervalSeconds = 10;
+export function getLaneStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    expireStaleLocks(context, project.id);
+    return {
+        ok: true,
+        lanes: lanesForProject(context, project.id, input.lane),
+        locks: laneLocksForProject(context, project.id, input.lane)
+    };
+}
+export function setLaneWorkspace(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    const workspacePath = resolveExistingPath(input.workspacePath);
+    const now = context.now();
+    const existing = laneRecord(context, project.id, lane);
+    context.db.run(`INSERT INTO lanes
+       (project_id, name, workspace_path, expected_branch, status, created_at, updated_at)
+     VALUES (?, ?, ?, ?, 'active', ?, ?)
+     ON CONFLICT(project_id, name) DO UPDATE SET
+       workspace_path = excluded.workspace_path,
+       expected_branch = excluded.expected_branch,
+       status = 'active',
+       updated_at = excluded.updated_at`, [project.id, lane, workspacePath, input.branch ?? null, existing?.created_at ?? now, now]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "lane.workspace_set",
+        payload: { project_id: project.id, lane, workspace_path: workspacePath, expected_branch: input.branch ?? null }
+    });
+    return { ok: true, lane: laneRecord(context, project.id, lane) };
+}
+export function checkLaneWorkspace(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = requireLane(context, project.id, normalizeLane(input.lane));
+    const workspacePath = resolveExistingPath(input.workspacePath);
+    if (workspacePath !== lane.workspace_path) {
+        throw new AppError("lane_workspace_mismatch", "Workspace path does not match registered lane workspace", 1, {
+            lane: lane.name,
+            expected_path: lane.workspace_path,
+            actual_path: workspacePath
+        });
+    }
+    const branch = detectBranch(workspacePath);
+    const branchMatches = lane.expected_branch && branch.current ? lane.expected_branch === branch.current : null;
+    return {
+        ok: true,
+        lane,
+        workspace_path: workspacePath,
+        branch: {
+            ...branch,
+            expected: lane.expected_branch,
+            matches_expected: branchMatches
+        }
+    };
+}
+export function acquireLaneLock(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
+    assertWorkerMayAcquireLaneLock(context, project.id, lane, input.workerId);
+    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    expireStaleLocks(context, project.id);
+    const active = activeLaneLock(context, project.id, lane);
+    if (active) {
+        if (active.worker_id === input.workerId) {
+            const now = context.now();
+            context.db.run(`UPDATE lane_locks
+         SET heartbeat_at = ?, expires_at = ?, updated_at = ?
+         WHERE id = ?`, [now, expiresAt(now, ttlSeconds), now, active.id]);
+            appendAudit(context, {
+                projectId: project.id,
+                eventType: "lane_lock.reused",
+                payload: { project_id: project.id, lane, worker_id: input.workerId, lock_id: active.id }
+            });
+            return { ok: true, lock: activeLaneLock(context, project.id, lane), reused: true };
+        }
+        throw new AppError("lane_lock_active", "Lane already has an active lock", 1, {
+            lane,
+            worker_id: active.worker_id,
+            expires_at: active.expires_at
+        });
+    }
+    const expired = latestExpiredLock(context, project.id, lane);
+    const now = context.now();
+    const leaseToken = crypto.randomUUID();
+    context.db.run(`INSERT INTO lane_locks
+      (project_id, lane, worker_id, status, lease_token, acquired_at, heartbeat_at,
+       expires_at, released_at, reason, metadata_json, created_at, updated_at)
+     VALUES (?, ?, ?, 'active', ?, ?, ?, ?, NULL, ?, '{}', ?, ?)`, [project.id, lane, input.workerId, leaseToken, now, now, expiresAt(now, ttlSeconds), input.reason, now, now]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: expired ? "lane_lock.expired_takeover" : "lane_lock.acquired",
+        reason: input.reason,
+        payload: { project_id: project.id, lane, worker_id: input.workerId, expired_lock_id: expired?.id ?? null }
+    });
+    return {
+        ok: true,
+        lock: activeLaneLock(context, project.id, lane),
+        reused: false,
+        ...(expired ? { expired_lock_id: expired.id } : {})
+    };
+}
+export function heartbeatLaneLock(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    if (input.workspacePath) {
+        requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
+    }
+    const lock = requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken);
+    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const now = context.now();
+    context.db.run(`UPDATE lane_locks SET heartbeat_at = ?, expires_at = ?, updated_at = ? WHERE id = ?`, [now, expiresAt(now, ttlSeconds), now, lock.id]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "lane_lock.heartbeat",
+        payload: { project_id: project.id, lane: lock.lane, worker_id: input.workerId, lock_id: lock.id }
+    });
+    return { ok: true, lock: activeLaneLock(context, project.id, lock.lane) };
+}
+export function releaseLaneLock(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    if (input.workspacePath) {
+        requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
+    }
+    const lock = requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken);
+    const now = context.now();
+    context.db.run(`UPDATE lane_locks
+     SET status = 'released', released_at = ?, reason = ?, updated_at = ?
+     WHERE id = ?`, [now, input.reason, now, lock.id]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "lane_lock.released",
+        reason: input.reason,
+        payload: { project_id: project.id, lane: lock.lane, worker_id: input.workerId, lock_id: lock.id }
+    });
+    return { ok: true, lock: laneLockById(context, lock.id) };
+}
+export async function waitForLaneLock(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
+    const timeoutSeconds = normalizeNonNegativeNumber(input.timeoutSeconds, 0, "timeout");
+    const pollIntervalSeconds = normalizePositiveNumber(input.pollIntervalSeconds, defaultPollIntervalSeconds, "poll-interval");
+    const start = Date.now();
+    while (true) {
+        expireStaleLocks(context, project.id);
+        const active = activeLaneLock(context, project.id, lane);
+        if (!active || active.worker_id === input.workerId) {
+            return { ok: true, available: true, lock: active ?? null };
+        }
+        if (timeoutSeconds > 0 && Date.now() - start >= timeoutSeconds * 1000) {
+            appendAudit(context, {
+                projectId: project.id,
+                eventType: "lane_lock.wait_timeout",
+                payload: { project_id: project.id, lane, worker_id: input.workerId, timeout_seconds: timeoutSeconds }
+            });
+            return { ok: true, available: false, timed_out: true, lock: active };
+        }
+        await delay(pollIntervalSeconds * 1000);
+    }
+}
+export function requireLaneLockOwner(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    if (input.workspacePath) {
+        requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
+    }
+    return requireOwnedActiveLock(context, project.id, lane, input.workerId);
+}
+export function ensureLaneWorkspace(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    const existing = laneRecord(context, project.id, lane);
+    if (existing) {
+        return existing;
+    }
+    const workspacePath = resolveExistingPath(input.workspacePath ?? project.root);
+    const now = context.now();
+    context.db.run(`INSERT INTO lanes
+       (project_id, name, workspace_path, expected_branch, status, created_at, updated_at)
+     VALUES (?, ?, ?, ?, 'active', ?, ?)`, [project.id, lane, workspacePath, input.branch ?? null, now, now]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "lane.workspace_set",
+        payload: { project_id: project.id, lane, workspace_path: workspacePath, expected_branch: input.branch ?? null }
+    });
+    return requireLane(context, project.id, lane);
+}
+export function laneRecord(context, projectId, lane) {
+    return context.db.get("SELECT * FROM lanes WHERE project_id = ? AND name = ?", [projectId, lane]);
+}
+function requireLane(context, projectId, lane) {
+    const record = laneRecord(context, projectId, lane);
+    if (!record) {
+        throw new AppError("lane_not_registered", `Lane is not registered: ${lane}`, 1, { lane });
+    }
+    return record;
+}
+function requireMatchingLaneWorkspace(context, projectId, lane, workspacePath) {
+    const record = requireLane(context, projectId, lane);
+    const actualPath = resolveExistingPath(workspacePath);
+    if (actualPath !== record.workspace_path) {
+        throw new AppError("lane_workspace_mismatch", "Workspace path does not match registered lane workspace", 1, {
+            lane: record.name,
+            expected_path: record.workspace_path,
+            actual_path: actualPath
+        });
+    }
+    return record;
+}
+function lanesForProject(context, projectId, lane) {
+    if (lane) {
+        return context.db.all("SELECT * FROM lanes WHERE project_id = ? AND name = ? ORDER BY name ASC", [
+            projectId,
+            normalizeLane(lane)
+        ]);
+    }
+    return context.db.all("SELECT * FROM lanes WHERE project_id = ? ORDER BY name ASC", [projectId]);
+}
+function laneLocksForProject(context, projectId, lane) {
+    if (lane) {
+        return context.db.all(`SELECT * FROM lane_locks WHERE project_id = ? AND lane = ? ORDER BY updated_at DESC, id DESC LIMIT 20`, [projectId, normalizeLane(lane)]);
+    }
+    return context.db.all(`SELECT * FROM lane_locks WHERE project_id = ? ORDER BY updated_at DESC, id DESC LIMIT 50`, [projectId]);
+}
+function activeLaneLock(context, projectId, lane) {
+    expireStaleLocks(context, projectId);
+    return context.db.get(`SELECT * FROM lane_locks
+     WHERE project_id = ? AND lane = ? AND status = 'active'
+     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId, lane]);
+}
+function requireOwnedActiveLock(context, projectId, lane, workerId, leaseToken) {
+    const lock = activeLaneLock(context, projectId, lane);
+    if (!lock) {
+        throw new AppError("lane_lock_not_active", "Lane has no active lock", 1, { lane });
+    }
+    if (lock.worker_id !== workerId) {
+        throw new AppError("lane_lock_owned_by_other_worker", "Lane lock is owned by another worker", 1, {
+            lane,
+            worker_id: lock.worker_id
+        });
+    }
+    if (leaseToken && lock.lease_token !== leaseToken) {
+        throw new AppError("lane_lock_token_mismatch", "Lane lock lease token does not match", 1, { lane });
+    }
+    return lock;
+}
+function latestExpiredLock(context, projectId, lane) {
+    return context.db.get(`SELECT * FROM lane_locks
+     WHERE project_id = ? AND lane = ? AND status = 'expired'
+     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId, lane]);
+}
+function assertWorkerMayAcquireLaneLock(context, projectId, lane, workerId) {
+    if (lane !== "merge") {
+        return;
+    }
+    const latest = context.db.get(`SELECT status, stop_reason, flow_kind FROM flow_sessions
+     WHERE project_id = ? AND worker_id = ? AND flow_kind IN ('merge_worker', 'merge_job')
+     ORDER BY updated_at DESC, rowid DESC LIMIT 1`, [projectId, workerId]);
+    if (latest?.status === "stopped") {
+        throw new AppError("merge_worker_stopped", "Stopped merge worker cannot acquire the merge lane lock until it registers a new active session", 1, {
+            worker_id: workerId,
+            flow_kind: latest.flow_kind,
+            stop_reason: latest.stop_reason
+        });
+    }
+}
+function laneLockById(context, id) {
+    return context.db.get("SELECT * FROM lane_locks WHERE id = ?", [id]);
+}
+function expireStaleLocks(context, projectId) {
+    const now = context.now();
+    context.db.run(`UPDATE lane_locks
+     SET status = 'expired', updated_at = ?
+     WHERE project_id = ? AND status = 'active' AND expires_at <= ?`, [now, projectId, now]);
+}
+function resolveExistingPath(value) {
+    const absolute = path.resolve(value);
+    if (!fs.existsSync(absolute)) {
+        throw new AppError("not_found", `Workspace path does not exist: ${absolute}`, 1);
+    }
+    return fs.realpathSync(absolute);
+}
+function detectBranch(workspacePath) {
+    const result = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    if (result.status !== 0) {
+        return { checked: false, current: null, error: result.stderr.trim() || result.error?.message || "git branch unavailable" };
+    }
+    return { checked: true, current: result.stdout.trim(), error: null };
+}
+function expiresAt(now, ttlSeconds) {
+    return new Date(new Date(now).getTime() + ttlSeconds * 1000).toISOString();
+}
+function normalizeLane(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized || !/^[a-z0-9._-]+$/.test(normalized)) {
+        throw new AppError("validation", "Lane name must contain only lowercase letters, numbers, dot, underscore, or hyphen", 2);
+    }
+    return normalized;
+}
+function normalizePositiveNumber(value, fallback, label) {
+    const normalized = value ?? fallback;
+    if (!Number.isFinite(normalized) || normalized <= 0) {
+        throw new AppError("validation", `--${label} must be a positive number`, 2);
+    }
+    return normalized;
+}
+function normalizeNonNegativeNumber(value, fallback, label) {
+    const normalized = value ?? fallback;
+    if (!Number.isFinite(normalized) || normalized < 0) {
+        throw new AppError("validation", `--${label} must be zero or a positive number`, 2);
+    }
+    return normalized;
+}
+async function delay(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/services/memory-permissions.js

@@ -0,0 +1,344 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+const schemaId = "dd-flow/memorybank-permissions-preflight@1";
+const flows = ["mb-init", "mb-upgrade", "mb-audit", "mb-fix", "mb-upgrade-review", "custom"];
+const modes = ["read", "write", "repair", "report_only"];
+const maxScannedFiles = 5000;
+export function preflightMemoryPermissions(options) {
+    const flow = requireEnum(options.flow, flows, "--flow");
+    const mode = requireEnum(options.mode, modes, "--mode");
+    const projectRoot = path.resolve(options.root);
+    const memoryBank = resolveInside(projectRoot, options.memoryBank);
+    const tasks = options.tasks ? resolveInside(projectRoot, options.tasks) : path.join(projectRoot, ".tasks");
+    const checks = [];
+    const platform = platformInfo(projectRoot);
+    checks.push(checkExistingDirectory("project-root-read", projectRoot, "read_existing_file", fs.constants.R_OK));
+    if (flow === "mb-init" && !fs.existsSync(memoryBank)) {
+        checks.push(checkCreateDirectory("memory-bank-create", memoryBank));
+    }
+    else {
+        checks.push(checkExistingDirectory("memory-bank-read", memoryBank, "read_existing_file", fs.constants.R_OK));
+        if (mode !== "read") {
+            checks.push(checkExistingDirectory("memory-bank-write", memoryBank, "create_file", fs.constants.W_OK | fs.constants.X_OK));
+            checks.push(...checkWritableTree(memoryBank, "memory-bank-existing-file"));
+            checks.push(probeDirectory("memory-bank-probe", memoryBank));
+        }
+    }
+    if (mode === "write" || mode === "repair" || mode === "report_only") {
+        if (fs.existsSync(tasks)) {
+            checks.push(checkExistingDirectory("tasks-write", tasks, "create_file", fs.constants.W_OK | fs.constants.X_OK));
+            checks.push(probeDirectory("tasks-probe", tasks));
+        }
+        else {
+            checks.push(checkCreateDirectory("tasks-create", tasks));
+        }
+    }
+    else {
+        checks.push({
+            id: "tasks-read-mode-skipped",
+            severity: "info",
+            path: displayPath(projectRoot, tasks),
+            operation: "create_directory",
+            status: "skipped",
+            reason: "ok",
+            side_effect: "none"
+        });
+    }
+    const errors = checks.filter((check) => check.severity === "error" && check.status === "failed").length;
+    const warnings = checks.filter((check) => check.severity === "warning").length;
+    const ok = errors === 0;
+    return {
+        schema_id: schemaId,
+        ok,
+        exit_code: ok ? 0 : 1,
+        flow,
+        mode,
+        platform,
+        targets: {
+            project_root: displayPath(projectRoot, projectRoot),
+            memory_bank: displayPath(projectRoot, memoryBank),
+            tasks: displayPath(projectRoot, tasks)
+        },
+        checks,
+        summary: {
+            errors,
+            warnings,
+            can_continue: ok
+        },
+        remediation: remediationFor(platform.family, projectRoot, checks)
+    };
+}
+function requireEnum(value, allowed, label) {
+    if (!allowed.includes(value)) {
+        throw new AppError("validation", `${label} is not supported`, 2, { value, allowed });
+    }
+    return value;
+}
+function resolveInside(projectRoot, input) {
+    return path.isAbsolute(input) ? path.resolve(input) : path.resolve(projectRoot, input);
+}
+function platformInfo(projectRoot) {
+    const user = safeUserInfo();
+    return {
+        os: os.platform(),
+        family: os.platform() === "win32" ? "windows" : "posix",
+        cwd: projectRoot,
+        user: user.username,
+        group: user.group
+    };
+}
+function safeUserInfo() {
+    try {
+        const info = os.userInfo();
+        return { username: info.username, group: typeof info.gid === "number" ? String(info.gid) : "" };
+    }
+    catch {
+        return { username: "", group: "" };
+    }
+}
+function checkExistingDirectory(id, target, operation, access) {
+    if (!fs.existsSync(target)) {
+        return failedCheck(id, target, operation, "not_found", "Path does not exist");
+    }
+    try {
+        const stat = fs.statSync(target);
+        if (!stat.isDirectory()) {
+            return failedCheck(id, target, operation, "unknown", "Path is not a directory", stat);
+        }
+        const immutable = detectImmutableFlag(target);
+        if (immutable) {
+            return failedCheck(id, target, "detect_flags", "immutable_flag", immutable, stat);
+        }
+        fs.accessSync(target, access);
+        return passedCheck(id, target, operation, stat);
+    }
+    catch (error) {
+        return failedCheck(id, target, operation, accessReason(error, access), errorMessage(error), safeStat(target));
+    }
+}
+function checkCreateDirectory(id, target) {
+    const parent = path.dirname(target);
+    if (!fs.existsSync(parent)) {
+        return failedCheck(id, target, "create_directory", "not_found", `Parent directory does not exist: ${parent}`);
+    }
+    try {
+        fs.accessSync(parent, fs.constants.W_OK | fs.constants.X_OK);
+        return passedCheck(id, target, "create_directory", safeStat(parent));
+    }
+    catch (error) {
+        return failedCheck(id, target, "create_directory", "not_writable", errorMessage(error), safeStat(parent));
+    }
+}
+function checkWritableTree(root, prefix) {
+    if (!fs.existsSync(root))
+        return [];
+    const checks = [];
+    const stack = [root];
+    let scanned = 0;
+    while (stack.length > 0 && scanned < maxScannedFiles) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch (error) {
+            checks.push(failedCheck(`${prefix}-read-${checks.length + 1}`, current, "read_existing_file", "not_readable", errorMessage(error), safeStat(current)));
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name === ".git")
+                continue;
+            const entryPath = path.join(current, entry.name);
+            scanned += 1;
+            if (entry.isDirectory()) {
+                stack.push(entryPath);
+                checks.push(checkExistingDirectory(`${prefix}-dir-${checks.length + 1}`, entryPath, "create_file", fs.constants.W_OK | fs.constants.X_OK));
+            }
+            else if (entry.isFile()) {
+                checks.push(checkExistingFile(`${prefix}-${checks.length + 1}`, entryPath, fs.constants.R_OK | fs.constants.W_OK));
+            }
+            if (scanned >= maxScannedFiles)
+                break;
+        }
+    }
+    if (scanned >= maxScannedFiles) {
+        checks.push({
+            id: `${prefix}-scan-limit`,
+            severity: "warning",
+            path: root,
+            operation: "stat_metadata",
+            status: "warning",
+            reason: "unknown",
+            fs_error: { message: `Stopped after ${maxScannedFiles} filesystem entries` },
+            side_effect: "none"
+        });
+    }
+    return checks;
+}
+function checkExistingFile(id, target, access) {
+    try {
+        const stat = fs.statSync(target);
+        const immutable = detectImmutableFlag(target);
+        if (immutable) {
+            return failedCheck(id, target, "detect_flags", "immutable_flag", immutable, stat);
+        }
+        fs.accessSync(target, access);
+        const ownerWarning = ownerMismatchWarning(id, target, stat);
+        return ownerWarning ?? passedCheck(id, target, "write_existing_file", stat);
+    }
+    catch (error) {
+        return failedCheck(id, target, "write_existing_file", accessReason(error, access), errorMessage(error), safeStat(target));
+    }
+}
+function ownerMismatchWarning(id, target, stat) {
+    if (os.platform() === "win32" || typeof process.getuid !== "function")
+        return undefined;
+    if (stat.uid === process.getuid())
+        return undefined;
+    return {
+        ...metadata(id, target, "stat_metadata", stat),
+        severity: "warning",
+        status: "warning",
+        reason: "owner_mismatch",
+        fs_error: { message: "Current user has effective write access, but file owner differs from current uid" },
+        side_effect: "none"
+    };
+}
+function probeDirectory(id, target) {
+    const probePath = path.join(target, `.dd-flow-permission-probe-${process.pid}-${Date.now()}`);
+    try {
+        fs.writeFileSync(probePath, "probe\n", { flag: "wx" });
+        fs.unlinkSync(probePath);
+        return {
+            ...metadata(id, target, "create_file", safeStat(target)),
+            severity: "info",
+            status: "passed",
+            reason: "ok",
+            side_effect: "temporary_probe_created_and_removed"
+        };
+    }
+    catch (error) {
+        try {
+            if (fs.existsSync(probePath))
+                fs.unlinkSync(probePath);
+        }
+        catch (cleanupError) {
+            return {
+                ...failedCheck(id, target, "delete_probe", "probe_failed", errorMessage(cleanupError), safeStat(target)),
+                side_effect: "temporary_probe_cleanup_failed"
+            };
+        }
+        return failedCheck(id, target, "create_file", "probe_failed", errorMessage(error), safeStat(target));
+    }
+}
+function passedCheck(id, target, operation, stat) {
+    return {
+        ...metadata(id, target, operation, stat),
+        severity: "info",
+        status: "passed",
+        reason: "ok",
+        side_effect: "none"
+    };
+}
+function failedCheck(id, target, operation, reason, message, stat) {
+    return {
+        ...metadata(id, target, operation, stat),
+        severity: "error",
+        status: "failed",
+        reason,
+        fs_error: { message },
+        side_effect: "none"
+    };
+}
+function metadata(id, target, operation, stat) {
+    return {
+        id,
+        path: target,
+        operation,
+        ...(stat ? statMetadata(stat) : {})
+    };
+}
+function statMetadata(stat) {
+    if (os.platform() === "win32")
+        return {};
+    return {
+        owner: String(stat.uid),
+        group: String(stat.gid),
+        mode: `0${(stat.mode & 0o777).toString(8)}`
+    };
+}
+function safeStat(target) {
+    try {
+        return fs.statSync(target);
+    }
+    catch {
+        return undefined;
+    }
+}
+function detectImmutableFlag(target) {
+    if (os.platform() === "win32")
+        return undefined;
+    if (os.platform() === "darwin" || os.platform() === "freebsd" || os.platform() === "openbsd") {
+        const result = spawnSync("ls", ["-ldO", target], { encoding: "utf8" });
+        if (result.status === 0 && /\b(uappnd|uchg|schg|sappnd)\b/.test(result.stdout)) {
+            return `immutable file flag detected: ${result.stdout.trim()}`;
+        }
+    }
+    if (os.platform() === "linux") {
+        const result = spawnSync("lsattr", ["-d", target], { encoding: "utf8" });
+        if (result.status === 0 && /^[-a-zA-Z]*i[-a-zA-Z]*\s/.test(result.stdout)) {
+            return `immutable file attribute detected: ${result.stdout.trim()}`;
+        }
+    }
+    return undefined;
+}
+function accessReason(error, access) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    if (code === "ENOENT")
+        return "not_found";
+    if (access & fs.constants.W_OK)
+        return os.platform() === "win32" ? "acl_denied" : "not_writable";
+    if (access & fs.constants.R_OK)
+        return "not_readable";
+    return "unknown";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function remediationFor(family, projectRoot, checks) {
+    const failingPaths = checks.filter((check) => check.severity === "error" && check.status === "failed").map((check) => displayPath(projectRoot, check.path));
+    if (failingPaths.length === 0)
+        return [];
+    const scoped = Array.from(new Set(failingPaths.filter((item) => item !== ".")));
+    const targets = scoped.length <= 2 ? scoped.join(" ") : ".memory-bank .tasks";
+    if (family === "windows") {
+        return [
+            {
+                platform: "win32",
+                title: "Restore write permissions for the current Windows user",
+                commands: [
+                    `attrib -R ${targets} /S /D`,
+                    `icacls ${targets} /grant "%USERNAME%:(OI)(CI)M" /T`
+                ],
+                requires_user_confirmation: true
+            }
+        ];
+    }
+    return [
+        {
+            platform: os.platform(),
+            title: "Return Memory Bank ownership and write access to the current user",
+            commands: [`sudo chown -R "$USER:$(id -gn)" ${targets}`, `chmod -R u+rwX ${targets}`],
+            requires_user_confirmation: true
+        }
+    ];
+}
+function displayPath(projectRoot, target) {
+    const relative = path.relative(projectRoot, target);
+    return relative === "" ? "." : relative;
+}