@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/lanes-checks.js

@@ -0,0 +1,941 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CLI_VERSION } from "../cli-version.js";
+import { loadLanesConfig } from "../lib/lanes/config.js";
+import { LanesError, isLanesError } from "../lib/lanes/errors.js";
+import { evaluateTrackerChecks } from "../lib/lanes/tracker-checks.js";
+import { LANE_STORE_UPGRADE_COMMAND, isLaneStoreVersionNewer, laneRecordPath, listLaneIds, listQuestionIds, questionRecordPath, readLane, readQuestion } from "../lib/lanes/store.js";
+import { createLocalTrackerStore } from "../lib/lanes/tracker-store.js";
+import { sessionLiveness } from "../lib/lanes/liveness.js";
+import { resolveLaneCompany } from "../lib/lanes/lane-company.js";
+import { DEFAULT_ORPHAN_USER_IDLE_HOURS, findOrphanLanes, parseOrphanMinAge, parseOrphanUserIdleHours, } from "../lib/lanes/orphans.js";
+import { LANES_RUNS_REL } from "../lib/lanes/spawn.js";
+import { assertNoSecretText } from "../lib/lanes/text-scan.js";
+import { checkCompanyPath } from "../lib/lanes/checked-company-path.js";
+export function mappingIncludesStory(mapping, storyId) {
+    return (mapping.storyPrefix === undefined || storyId.startsWith(mapping.storyPrefix))
+        && (mapping.excludePrefix === undefined || !storyId.startsWith(mapping.excludePrefix));
+}
+function mappingsOverlap(left, right) {
+    const includes = [left.storyPrefix, right.storyPrefix].filter((value) => value !== undefined);
+    if (includes.length === 2 && !includes[0].startsWith(includes[1]) && !includes[1].startsWith(includes[0]))
+        return false;
+    const commonPrefix = includes.sort((a, b) => b.length - a.length)[0] ?? "";
+    return ![left.excludePrefix, right.excludePrefix].some((excluded) => excluded !== undefined && commonPrefix.startsWith(excluded));
+}
+function ambiguousProjectMappings(mappings) {
+    const byProject = new Map();
+    for (const mapping of mappings)
+        byProject.set(mapping.projectId, [...(byProject.get(mapping.projectId) ?? []), mapping]);
+    const ambiguous = new Map();
+    for (const [projectId, rows] of byProject) {
+        const conflicts = new Set();
+        for (let i = 0; i < rows.length; i++) {
+            for (let j = i + 1; j < rows.length; j++) {
+                if (mappingsOverlap(rows[i], rows[j])) {
+                    conflicts.add(rows[i].team);
+                    conflicts.add(rows[j].team);
+                }
+            }
+        }
+        if (conflicts.size > 0)
+            ambiguous.set(projectId, [...conflicts].sort());
+    }
+    return ambiguous;
+}
+function fail(error, message, details = {}) {
+    throw new LanesError(error, message, details);
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validSegment(value, field) {
+    const normalized = value.trim();
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(normalized) || normalized === "." || normalized === "..") {
+        return fail("tracker_input_invalid", `${field} must be a safe path segment`, { field });
+    }
+    return normalized;
+}
+function parseTimestamp(value, field, file) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        return fail("tracker_checks_input_invalid", `${field} must be a valid timestamp`, { path: file, field });
+    }
+    return value;
+}
+function readJsonObject(file, missing = "error") {
+    let raw;
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            return fail("tracker_checks_input_invalid", "Checks input must be a regular file", { path: file });
+        }
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT" && missing === "empty")
+            return null;
+        if (isLanesError(err))
+            throw err;
+        return fail("tracker_checks_input_unreadable", `Checks input could not be read: ${err instanceof Error ? err.message : String(err)}`, { path: file });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return fail("tracker_checks_input_malformed", "Checks input contains invalid JSON", { path: file });
+    }
+    if (!isObject(parsed))
+        return fail("tracker_checks_input_invalid", "Checks input must be a JSON object", { path: file });
+    return parsed;
+}
+function projectFromPrdReference(root, company, raw, registryPath) {
+    if (typeof raw !== "string" || raw.trim() === "") {
+        return fail("tracker_checks_mapping_invalid", "Team mapping needs a PRD path", { path: registryPath });
+    }
+    if (path.isAbsolute(raw))
+        return fail("tracker_checks_mapping_invalid", "Mapped path must be relative to the HQ root", { path: registryPath });
+    const candidate = path.resolve(root, raw);
+    const segments = path.relative(fs.realpathSync(root), candidate).split(path.sep);
+    if (segments[0] === "companies" && segments[1] !== company)
+        return null;
+    const absolute = checkCompanyPath(root, company, raw, registryPath);
+    const relative = path.relative(fs.realpathSync(root), absolute).split(path.sep);
+    if (relative[0] === "companies" && relative[1] === company && relative[2] === "projects" && relative.length === 5 && relative[4] === "prd.json") {
+        return validSegment(relative[3], "project");
+    }
+    // Older local lanes may point at a personal PRD. Use only its project slug
+    // to join against the active company's own project directory; never read it.
+    if (relative[0] === "personal" && relative[1] === "projects" && relative.length === 4 && relative[3] === "prd.json") {
+        return validSegment(relative[2], "project");
+    }
+    return null;
+}
+function projectDirectories(root, company) {
+    const projectsRoot = path.join(root, "companies", company, "projects");
+    let realProjectsRoot;
+    try {
+        realProjectsRoot = fs.realpathSync(projectsRoot);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        return fail("tracker_checks_input_unreadable", `Company project directory could not be resolved: ${err instanceof Error ? err.message : String(err)}`, { path: projectsRoot });
+    }
+    const projectsRelative = path.relative(fs.realpathSync(root), realProjectsRoot).split(path.sep);
+    if (projectsRelative[0] !== "companies" || projectsRelative[1] !== company || projectsRelative[2] !== "projects") {
+        return fail("tracker_checks_mapping_invalid", "Company project directory resolves outside the active tenant", { path: projectsRoot });
+    }
+    try {
+        return fs.readdirSync(projectsRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .filter((name) => /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(name));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        return fail("tracker_checks_input_unreadable", `Company project directory could not be read: ${err instanceof Error ? err.message : String(err)}`, { path: projectsRoot });
+    }
+}
+function projectHasTrackerRecords(root, company, projectId) {
+    const projectPath = path.join(root, "companies", company, "projects", projectId);
+    const trackerRoot = path.join(projectPath, "tracker");
+    let trackerStat;
+    try {
+        trackerStat = fs.lstatSync(trackerRoot);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        return fail("tracker_checks_input_unreadable", `Project tracker directory could not be inspected: ${err instanceof Error ? err.message : String(err)}`, { path: trackerRoot });
+    }
+    if (!trackerStat.isDirectory() || trackerStat.isSymbolicLink()) {
+        return fail("tracker_checks_input_invalid", "Project tracker path must be a regular directory", { path: trackerRoot });
+    }
+    for (const kind of ["blocker", "kpi", "okr", "directive"]) {
+        const directory = path.join(trackerRoot, kind);
+        let stat;
+        try {
+            stat = fs.lstatSync(directory);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            return fail("tracker_checks_input_unreadable", `Project tracker records could not be inspected: ${err instanceof Error ? err.message : String(err)}`, { path: directory });
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            return fail("tracker_checks_input_invalid", "Project tracker record path must be a regular directory", { path: directory });
+        }
+        try {
+            if (fs.readdirSync(directory).some((name) => name.endsWith(".json")))
+                return true;
+        }
+        catch (err) {
+            return fail("tracker_checks_input_unreadable", `Project tracker records could not be listed: ${err instanceof Error ? err.message : String(err)}`, { path: directory });
+        }
+    }
+    return false;
+}
+export function loadProjectMappings(root, company, requestedProject) {
+    const registryPath = path.join(root, "workspace", "lane-briefs", "juniors.json");
+    const registry = readJsonObject(registryPath, "empty");
+    const mappings = new Map();
+    if (registry !== null) {
+        if (!Array.isArray(registry.juniors))
+            return fail("tracker_checks_mapping_invalid", "Team mapping must contain a juniors array", { path: registryPath });
+        for (const [index, entry] of registry.juniors.entries()) {
+            if (!isObject(entry))
+                return fail("tracker_checks_mapping_invalid", "Team mapping row must be an object", { path: registryPath, index });
+            const projectId = projectFromPrdReference(root, company, entry.prd, registryPath);
+            if (projectId === null)
+                continue;
+            if (typeof entry.team !== "string" || typeof entry.lane !== "string" || typeof entry.status !== "string") {
+                return fail("tracker_checks_mapping_invalid", "Active team mapping needs team, lane, and status paths", { path: registryPath, index });
+            }
+            const team = validSegment(entry.team, "team");
+            const leadLaneId = validSegment(entry.lane, "lead lane id");
+            const statusPath = checkCompanyPath(root, company, entry.status, registryPath);
+            const parsePrefix = (field) => {
+                const value = entry[field];
+                if (value === undefined)
+                    return undefined;
+                if (typeof value !== "string" || value.trim() === "") {
+                    return fail("tracker_checks_mapping_invalid", `${field} must be a non-empty string`, { path: registryPath, index, field });
+                }
+                return value.trim();
+            };
+            const storyPrefix = parsePrefix("story_prefix");
+            const excludePrefix = parsePrefix("exclude_prefix");
+            const key = `${projectId}:${team}:${index}`;
+            mappings.set(key, { projectId, team, leadLaneId, statusPath, ...(storyPrefix === undefined ? {} : { storyPrefix }), ...(excludePrefix === undefined ? {} : { excludePrefix }) });
+        }
+    }
+    const projectsRoot = path.join(root, "companies", company, "projects");
+    const knownProjectIds = new Set(projectDirectories(root, company));
+    for (const projectId of knownProjectIds) {
+        if (projectHasTrackerRecords(root, company, projectId) && ![...mappings.values()].some((mapping) => mapping.projectId === projectId)) {
+            mappings.set(`${projectId}:tracker`, {
+                projectId,
+                team: projectId,
+                statusPath: path.join(projectsRoot, projectId, "manager-status.json"),
+            });
+        }
+    }
+    if (requestedProject !== undefined) {
+        const projectId = validSegment(requestedProject, "project");
+        if (!knownProjectIds.has(projectId) && ![...mappings.values()].some((mapping) => mapping.projectId === projectId)) {
+            return fail("tracker_project_not_found", "Project directory was not found for this company", { project_id: projectId, path: path.join(projectsRoot, projectId) });
+        }
+        return new Map([...mappings].filter(([, mapping]) => mapping.projectId === projectId));
+    }
+    return mappings;
+}
+export function readProject(root, company, prdPath, tolerantStories = false) {
+    checkCompanyPath(root, company, path.relative(root, prdPath), prdPath);
+    const parsed = readJsonObject(prdPath);
+    if (parsed === null)
+        return fail("tracker_checks_input_invalid", "Project task list must be a JSON object", { path: prdPath });
+    const metadata = isObject(parsed.metadata) ? parsed.metadata : undefined;
+    const rawCompany = parsed.company ?? metadata?.company;
+    const projectCompany = typeof rawCompany === "string"
+        ? rawCompany
+        : isObject(rawCompany) && typeof rawCompany.slug === "string"
+            ? rawCompany.slug
+            : null;
+    if (rawCompany !== undefined && rawCompany !== null && projectCompany === null) {
+        return fail("tracker_project_invalid", "Project company metadata must name a company slug", { path: prdPath });
+    }
+    if (projectCompany !== null && projectCompany !== company) {
+        return fail("tracker_company_mismatch", "Project company does not match the active HQ company", { active_company: company, project_company: projectCompany, path: prdPath });
+    }
+    const rawStories = parsed.userStories === undefined ? parsed.stories : parsed.userStories;
+    if (!Array.isArray(rawStories))
+        return fail("tracker_checks_input_invalid", "Project task list must contain a userStories or stories array", { path: prdPath });
+    const errors = [];
+    const stories = rawStories.flatMap((story, index) => {
+        if (!isObject(story) || typeof story.id !== "string" || story.id.trim() === "") {
+            if (tolerantStories) {
+                errors.push({ path: prdPath, field: `userStories[${index}]`, message: "Project task list contains a story without an id" });
+                return [];
+            }
+            return fail("tracker_checks_input_invalid", "Project task list contains a story without an id", { path: prdPath, index });
+        }
+        if (story.prs !== undefined && !Array.isArray(story.prs)) {
+            if (tolerantStories) {
+                errors.push({ path: prdPath, field: "prs", message: "Project story prs must be an array", story_id: story.id });
+                return [{ ...story, prs: [] }];
+            }
+            return fail("tracker_checks_input_invalid", "Project story prs must be an array", { path: prdPath, story_id: story.id });
+        }
+        return [story];
+    });
+    try {
+        return { stories, mtime: fs.statSync(prdPath).mtimeMs, ...(tolerantStories ? { errors } : {}) };
+    }
+    catch (err) {
+        return fail("tracker_checks_input_unreadable", `Project task list could not be stat'ed: ${err instanceof Error ? err.message : String(err)}`, { path: prdPath });
+    }
+}
+function readStatusUpdatedAt(statusPath) {
+    const status = readJsonObject(statusPath, "empty");
+    if (status === null)
+        return null;
+    return parseTimestamp(status.updated_at, "status.updated_at", statusPath);
+}
+function storyIsDone(story) {
+    const state = typeof story.state === "string" ? story.state : story.status;
+    return story.passes === true || state === "done" || state === "dropped";
+}
+function pullRequestReferences(value, out = new Set(), seen = new Set()) {
+    if (typeof value === "string") {
+        const matches = value.match(/https?:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/pull\/[0-9]+(?:\/)?/g) ?? [];
+        for (const match of matches)
+            out.add(match.replace(/\/$/, ""));
+    }
+    else if (value !== null && typeof value === "object" && !seen.has(value)) {
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                pullRequestReferences(item, out, seen);
+        }
+        else {
+            const object = value;
+            const state = object.state ?? object.status;
+            if (object.merged === true || object.closed === true || state === "merged" || state === "closed")
+                return [...out].sort();
+            for (const nested of Object.values(object))
+                pullRequestReferences(nested, out, seen);
+        }
+    }
+    return [...out].sort();
+}
+function laneMatchesProject(lane, projectId) {
+    return lane.project_id === projectId || (lane.stories ?? []).some((story) => story.project_id === projectId);
+}
+function laneMetadataMatchesScope(record, company, projectIds) {
+    const laneCompany = isObject(record.company) ? record.company : null;
+    if (laneCompany?.slug !== company.slug || laneCompany.uid !== company.uid)
+        return false;
+    if (typeof record.project_id === "string" && projectIds.has(record.project_id))
+        return true;
+    return Array.isArray(record.stories) && record.stories.some((story) => isObject(story) && typeof story.project_id === "string" && projectIds.has(story.project_id));
+}
+function readScopedLanes(root, company, projects) {
+    const projectIds = new Set(projects.map((project) => project.projectId));
+    if (projectIds.size === 0)
+        return [];
+    return listLaneIds(root).flatMap((id) => {
+        const file = laneRecordPath(root, id);
+        const metadata = readJsonObject(file);
+        if (metadata === null)
+            return fail("tracker_checks_input_unreadable", "Lane record could not be read while checking its scope", { path: file });
+        if (!laneMetadataMatchesScope(metadata, company, projectIds))
+            return [];
+        return [readLane(root, id)];
+    });
+}
+function orphanSessionState(root, sessionId, now, deps) {
+    if (deps.sessionState)
+        return deps.sessionState(root, sessionId, now);
+    return sessionLiveness(root, sessionId, { nowMs: now.getTime() });
+}
+const MAX_ORPHAN_SENIOR_DEPTH = 64;
+function readOrphanLaneScopes(root) {
+    return new Map(listLaneIds(root).map((id) => {
+        const file = laneRecordPath(root, id);
+        const metadata = readJsonObject(file);
+        if (metadata === null)
+            return fail("tracker_checks_input_unreadable", "Lane record could not be read while resolving orphan scope", { path: file });
+        const companyRef = (value) => isObject(value) && typeof value.slug === "string" && typeof value.uid === "string"
+            ? { slug: value.slug, uid: value.uid }
+            : null;
+        const meshCompany = companyRef(metadata.mesh_company);
+        const lane = {
+            lane_id: id,
+            company: companyRef(metadata.company),
+            ...(meshCompany === null ? {} : { mesh_company: meshCompany }),
+            project_id: typeof metadata.project_id === "string" ? metadata.project_id : "",
+        };
+        const seniorLaneId = isObject(metadata.senior) && metadata.senior.kind === "lane" && typeof metadata.senior.id === "string"
+            ? metadata.senior.id
+            : undefined;
+        const projectIds = [lane.project_id];
+        if (Array.isArray(metadata.stories)) {
+            for (const story of metadata.stories) {
+                if (isObject(story) && typeof story.project_id === "string")
+                    projectIds.push(story.project_id);
+            }
+        }
+        return [id, { lane, ...(seniorLaneId === undefined ? {} : { seniorLaneId }), projectIds }];
+    }));
+}
+function orphanCompanyResolution(root, scope, scopesById) {
+    const direct = resolveLaneCompany(root, scope.lane);
+    if (direct.company !== null)
+        return direct;
+    const visited = new Set([scope.lane.lane_id]);
+    let current = scope;
+    for (let depth = 0; depth < MAX_ORPHAN_SENIOR_DEPTH; depth += 1) {
+        const seniorId = current.seniorLaneId;
+        if (seniorId === undefined)
+            break;
+        if (visited.has(seniorId))
+            break;
+        visited.add(seniorId);
+        const senior = scopesById.get(seniorId);
+        if (senior === undefined)
+            break;
+        const resolved = resolveLaneCompany(root, senior.lane);
+        if (resolved.company !== null)
+            return { company: resolved.company, source: "senior" };
+        current = senior;
+    }
+    return { company: null, source: "unresolved" };
+}
+function orphanLastActivityAt(root, lane) {
+    const updatedAt = Date.parse(lane.updated_at);
+    if (!Number.isFinite(updatedAt))
+        return Number.NaN;
+    const recordedEnvelopeAt = lane.last_envelope === undefined ? Number.NaN : Date.parse(lane.last_envelope.at);
+    let latest = Number.isFinite(recordedEnvelopeAt) ? Math.max(updatedAt, recordedEnvelopeAt) : updatedAt;
+    const envelopesDirectory = path.join(root, LANES_RUNS_REL, lane.lane_id, "envelopes");
+    let entries;
+    try {
+        entries = fs.readdirSync(envelopesDirectory, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return latest;
+        return fail("orphan_envelope_unreadable", "Lane envelope directory could not be read", { lane_id: lane.lane_id });
+    }
+    for (const entry of entries) {
+        if (!entry.name.endsWith(".json") || entry.name.startsWith("."))
+            continue;
+        const file = path.join(envelopesDirectory, entry.name);
+        try {
+            const stat = fs.lstatSync(file);
+            if (stat.isFile() && !stat.isSymbolicLink() && Number.isFinite(stat.mtimeMs)) {
+                latest = Math.max(latest, stat.mtimeMs);
+            }
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            return fail("orphan_envelope_unreadable", "Lane envelope timestamp could not be read", { lane_id: lane.lane_id });
+        }
+    }
+    return latest;
+}
+function orphanLaneHasOpenStory(root, lane, company) {
+    const carriedStories = lane.stories ?? [];
+    const references = [];
+    const addReference = (project_id, story_id) => {
+        if (!references.some((reference) => reference.project_id === project_id && reference.story_id === story_id)) {
+            references.push({ project_id, story_id });
+        }
+    };
+    if (lane.story_id !== "")
+        addReference(lane.project_id, lane.story_id);
+    for (const story of carriedStories) {
+        addReference(story.project_id, story.story_id);
+        if (story.status !== "done")
+            return true;
+    }
+    if (references.length === 0)
+        return false;
+    if (company === null)
+        return true;
+    for (const reference of references) {
+        const resolution = resolveLaneCompany(root, {
+            lane_id: lane.lane_id,
+            company: lane.company,
+            project_id: reference.project_id,
+        });
+        if (resolution.company === null || resolution.company.slug !== company.slug || resolution.company.uid !== company.uid) {
+            return true;
+        }
+        const projectId = validSegment(reference.project_id, "project");
+        const prdPath = path.join(root, "companies", company.slug, "projects", projectId, "prd.json");
+        const stories = readProject(root, company.slug, prdPath, true).stories;
+        const matching = stories.filter((story) => story.id === reference.story_id);
+        if (matching.some((story) => !storyIsDone(story)))
+            return true;
+    }
+    return false;
+}
+function orphanFindings(root, company, now, minAgeMinutes, deps, projectId, unscoped = company === null, userIdleHours = DEFAULT_ORPHAN_USER_IDLE_HOURS) {
+    const scopesById = readOrphanLaneScopes(root);
+    const companyByLane = new Map();
+    const selectedScopes = [...scopesById.values()].filter((scope) => {
+        if (projectId !== undefined && !scope.projectIds.includes(projectId))
+            return false;
+        const rawCompany = scope.lane.company;
+        if (company !== null && rawCompany !== null && (rawCompany.slug !== company.slug || rawCompany.uid !== company.uid))
+            return false;
+        const resolution = orphanCompanyResolution(root, scope, scopesById);
+        companyByLane.set(scope.lane.lane_id, resolution);
+        if (unscoped)
+            return resolution.company === null;
+        return company !== null && resolution.company?.slug === company.slug && resolution.company.uid === company.uid;
+    });
+    const selectedLanes = selectedScopes.map((scope) => readLane(root, scope.lane.lane_id));
+    const candidates = selectedLanes.filter((lane) => projectId === undefined ||
+        lane.project_id === projectId || (lane.stories ?? []).some((story) => story.project_id === projectId));
+    const candidateIds = new Set(candidates.map((lane) => lane.lane_id));
+    const lanesForFinding = new Map(candidates.map((lane) => [lane.lane_id, lane]));
+    for (const lane of candidates) {
+        if (lane.senior.kind !== "lane" || lane.senior.id === undefined || lanesForFinding.has(lane.senior.id))
+            continue;
+        if (scopesById.has(lane.senior.id))
+            lanesForFinding.set(lane.senior.id, readLane(root, lane.senior.id));
+    }
+    return findOrphanLanes({
+        lanes: [...lanesForFinding.values()],
+        candidateLaneIds: candidateIds,
+        now,
+        minAgeMinutes,
+        userIdleHours,
+        sessionState: (sessionId, at) => orphanSessionState(root, sessionId, at, deps),
+        lastActivityAt: (lane) => orphanLastActivityAt(root, lane),
+        hasOpenStory: (lane) => orphanLaneHasOpenStory(root, lane, companyByLane.get(lane.lane_id)?.company ?? null),
+    })
+        .filter((finding) => candidateIds.has(finding.lane_id))
+        .map((finding) => ({
+        ...finding,
+        company_source: companyByLane.get(finding.lane_id)?.source ?? "unresolved",
+    }));
+}
+function sameCompanyLane(lane, company) {
+    return lane.company?.slug === company.slug && lane.company.uid === company.uid;
+}
+function questionSurfacingState(root, questions) {
+    const statePath = path.join(root, "workspace", "lane-briefs", "ops-board-state.json");
+    const state = readJsonObject(statePath, "empty");
+    const surfaced = new Map();
+    if (state === null)
+        return surfaced;
+    if (state.questions !== undefined && !isObject(state.questions)) {
+        return fail("tracker_checks_input_invalid", "Owner question state must contain a questions object", { path: statePath });
+    }
+    const questionState = isObject(state.questions) ? state.questions : {};
+    for (const question of questions) {
+        const entry = questionState[question.id];
+        if (entry === undefined) {
+            surfaced.set(question.id, null);
+            continue;
+        }
+        if (!isObject(entry))
+            return fail("tracker_checks_input_invalid", "Owner question state must be an object", { path: statePath, question_id: question.id });
+        const at = entry.surfaced_at === undefined || entry.surfaced_at === null
+            ? null
+            : parseTimestamp(entry.surfaced_at, "surfaced_at", statePath);
+        surfaced.set(question.id, at);
+    }
+    return surfaced;
+}
+function questionMetadataMatchesScope(record, company, projectId) {
+    if (record.company === null)
+        return false;
+    if (!isObject(record.company))
+        return true;
+    if (typeof record.company.slug === "string" && record.company.slug !== company.slug)
+        return false;
+    if (typeof record.company.uid === "string" && record.company.uid !== company.uid)
+        return false;
+    if (record.company.slug === company.slug && record.company.uid === company.uid && projectId !== undefined &&
+        typeof record.project_id === "string" && record.project_id !== projectId)
+        return false;
+    return true;
+}
+export function loadCompanyQuestionRecords(root, company, projectId) {
+    const records = listQuestionIds(root)
+        .flatMap((id) => {
+        const file = questionRecordPath(root, id);
+        const metadata = readJsonObject(file);
+        if (metadata === null)
+            return fail("tracker_checks_input_unreadable", "Question record could not be read while checking its scope", { path: file });
+        if (!questionMetadataMatchesScope(metadata, company, projectId))
+            return [];
+        const question = readQuestion(root, id);
+        return question.company?.slug === company.slug && question.company.uid === company.uid &&
+            (projectId === undefined || question.project_id === projectId) ? [question] : [];
+    });
+    return records;
+}
+function readCompanyQuestions(root, company, projectId) {
+    const records = loadCompanyQuestionRecords(root, company, projectId);
+    const surfacedAt = questionSurfacingState(root, records.map((question) => ({
+        id: question.question_id,
+        status: question.status,
+        asked_at: question.asked_at,
+        routing_history: question.routing_history.map((entry) => ({ at: entry.at, audience_kind: entry.audience.kind })),
+        surfaced_at: null,
+    })));
+    return records.map((question) => ({
+        id: question.question_id,
+        status: question.status,
+        asked_at: question.asked_at,
+        routing_history: question.routing_history.map((entry) => ({ at: entry.at, audience_kind: entry.audience.kind })),
+        surfaced_at: surfacedAt.get(question.question_id) ?? null,
+    }));
+}
+export function readTeamInputs(root, company, projects, lanes) {
+    const inputs = [];
+    for (const project of projects) {
+        const projectPath = path.join(root, "companies", company.slug, "projects", project.projectId);
+        const prdPath = path.join(projectPath, "prd.json");
+        const { stories, mtime } = readProject(root, company.slug, prdPath);
+        const teamLanes = lanes.filter((lane) => sameCompanyLane(lane, company) && laneMatchesProject(lane, project.projectId)
+            && (lane.lane_id === project.leadLaneId || mappingIncludesStory(project, lane.story_id)));
+        const lead = project.leadLaneId === undefined
+            ? undefined
+            : teamLanes.find((lane) => lane.lane_id === project.leadLaneId);
+        const openStories = stories.filter((story) => mappingIncludesStory(project, String(story.id)) && !storyIsDone(story));
+        const openPrRefs = new Set();
+        for (const story of openStories) {
+            for (const ref of pullRequestReferences(story.prs ?? []))
+                openPrRefs.add(ref);
+        }
+        for (const lane of teamLanes) {
+            for (const ref of pullRequestReferences(lane.last_envelope?.artifacts ?? []))
+                openPrRefs.add(ref);
+        }
+        const runningWorkers = teamLanes
+            .filter((lane) => lane.lane_id !== project.leadLaneId && lane.senior.kind === "lane" && lane.state === "running")
+            .map((lane) => lane.lane_id);
+        inputs.push({
+            team: project.team,
+            project_id: project.projectId,
+            ...(lead ? { lead_lane: { id: lead.lane_id, state: lead.state } } : {}),
+            open_story_ids: openStories.map((story) => String(story.id)),
+            open_pr_refs: [...openPrRefs].sort(),
+            running_worker_ids: runningWorkers,
+            status_path: project.statusPath,
+            status_updated_at: readStatusUpdatedAt(project.statusPath),
+            task_list_path: prdPath,
+            task_list_updated_at: new Date(mtime).toISOString(),
+        });
+    }
+    return inputs;
+}
+export function pathForTrackerRecord(projectDirectory, kind, id) {
+    return path.join(projectDirectory, "tracker", kind, `${id}.json`);
+}
+function recordInvalid(kind, record, projectDirectory, field) {
+    return fail("tracker_checks_record_invalid", `Tracker ${kind} record has invalid ${field}`, {
+        kind,
+        id: record.id,
+        field,
+        path: pathForTrackerRecord(projectDirectory, kind, record.id),
+    });
+}
+function requiredRecordDate(kind, record, projectDirectory, field) {
+    const value = record[field];
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)))
+        return recordInvalid(kind, record, projectDirectory, field);
+    return value;
+}
+function requiredRecordTimestamp(kind, record, projectDirectory, field, value) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)))
+        return parseTimestamp(value, field, pathForTrackerRecord(projectDirectory, kind, record.id));
+    return value;
+}
+function listTrackerRecords(projectDirectory, kind) {
+    try {
+        return createLocalTrackerStore(projectDirectory).list(kind);
+    }
+    catch (err) {
+        if (isLanesError(err) && typeof err.details.path === "string")
+            throw err;
+        return fail("tracker_checks_store_unreadable", `Tracker ${kind} records could not be read: ${err instanceof Error ? err.message : String(err)}`, { path: path.join(projectDirectory, "tracker", kind) });
+    }
+}
+/** Report loader that preserves valid records while making every unreadable file visible. */
+export function listTrackerRecordsTolerant(projectDirectory, kind) {
+    const root = path.join(projectDirectory, "tracker");
+    const directory = path.join(projectDirectory, "tracker", kind);
+    let names;
+    try {
+        const rootStat = fs.lstatSync(root);
+        if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+            return { records: [], errors: [{ path: root, field: "directory", message: "Tracker storage path must be a regular directory" }] };
+        }
+        const stat = fs.lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            return { records: [], errors: [{ path: directory, field: "directory", message: "Tracker record path must be a regular directory" }] };
+        }
+        names = fs.readdirSync(directory).filter((name) => name.endsWith(".json")).sort();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { records: [], errors: [] };
+        return { records: [], errors: [{ path: directory, field: "directory", message: `Tracker records could not be listed: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+    const store = createLocalTrackerStore(projectDirectory);
+    const records = [];
+    const errors = [];
+    for (const name of names) {
+        const id = name.slice(0, -5);
+        const file = path.join(directory, name);
+        try {
+            const record = store.read(kind, id);
+            if (record !== null)
+                records.push(record);
+        }
+        catch (err) {
+            const details = isLanesError(err) ? err.details : {};
+            errors.push({
+                path: typeof details.path === "string" ? details.path : file,
+                field: typeof details.field === "string" ? details.field : "record",
+                message: err instanceof Error ? err.message : String(err),
+                record_id: typeof details.id === "string" ? details.id : id,
+            });
+        }
+    }
+    records.sort((a, b) => b.updated_at.localeCompare(a.updated_at) || a.id.localeCompare(b.id));
+    return { records, errors };
+}
+async function readTrackerCheckRecords(root, company, projects) {
+    const blockers = [];
+    const kpis = [];
+    const directives = [];
+    for (const project of [...new Map(projects.map((project) => [project.projectId, project])).values()]) {
+        const absoluteDirectory = path.join(root, "companies", company.slug, "projects", project.projectId);
+        const store = createLocalTrackerStore(absoluteDirectory);
+        const records = {
+            blocker: await store.list("blocker"),
+            kpi: await store.list("kpi"),
+            directive: await store.list("directive"),
+        };
+        for (const record of records.blocker) {
+            if (record.company !== company.slug || record.project_id !== project.projectId)
+                continue;
+            const openedAt = requiredRecordDate("blocker", record, absoluteDirectory, "opened_at");
+            const resolvedAt = record.resolved_at;
+            if (resolvedAt !== null && (typeof resolvedAt !== "string" || !Number.isFinite(Date.parse(resolvedAt))))
+                recordInvalid("blocker", record, absoluteDirectory, "resolved_at");
+            const nextStep = record.next_step;
+            if (nextStep !== undefined && nextStep !== null && typeof nextStep !== "string")
+                recordInvalid("blocker", record, absoluteDirectory, "next_step");
+            blockers.push({ id: record.id, opened_at: openedAt, resolved_at: resolvedAt, next_step: typeof nextStep === "string" ? nextStep : null });
+        }
+        for (const record of records.kpi) {
+            if (record.company !== company.slug || record.project_id !== project.projectId)
+                continue;
+            const createdAt = requiredRecordDate("kpi", record, absoluteDirectory, "created_at");
+            if (!Array.isArray(record.values))
+                recordInvalid("kpi", record, absoluteDirectory, "values");
+            const values = record.values.map((value) => {
+                if (!isObject(value))
+                    recordInvalid("kpi", record, absoluteDirectory, "values");
+                return { at: requiredRecordTimestamp("kpi", record, absoluteDirectory, "values[].at", value.at) };
+            });
+            kpis.push({ id: record.id, created_at: createdAt, values });
+        }
+        for (const record of records.directive) {
+            if (record.company !== company.slug || record.project_id !== project.projectId)
+                continue;
+            const createdAt = requiredRecordDate("directive", record, absoluteDirectory, "created_at");
+            if (!Array.isArray(record.teams) || record.teams.some((team) => typeof team !== "string"))
+                recordInvalid("directive", record, absoluteDirectory, "teams");
+            if (!Array.isArray(record.acknowledgements))
+                recordInvalid("directive", record, absoluteDirectory, "acknowledgements");
+            const acknowledgements = record.acknowledgements.map((ack) => {
+                if (!isObject(ack) || typeof ack.team !== "string" || typeof ack.lane_id !== "string")
+                    recordInvalid("directive", record, absoluteDirectory, "acknowledgements");
+                return { team: ack.team, lane_id: ack.lane_id, at: requiredRecordTimestamp("directive", record, absoluteDirectory, "acknowledgements[].at", ack.at) };
+            });
+            directives.push({ id: record.id, created_at: createdAt, teams: record.teams, acknowledgements });
+        }
+    }
+    return { blockers, kpis, directives };
+}
+export async function resolveTrackerCompany(deps, requested) {
+    const company = await deps.resolveCompany(requested);
+    if (!company.slug)
+        fail("tracker_company_unresolved", "The active HQ company could not be resolved", {});
+    return company;
+}
+async function checkReport(root, company, projects, directiveProjects, projectFilter, minAgeMinutes, now, deps, projectErrors) {
+    const selectedProjects = [...projects.values()];
+    const laneRecords = readScopedLanes(root, company, selectedProjects);
+    const warnings = laneRecords.flatMap((lane) => {
+        const storedVersion = [lane.written_by_version, lane.owner_written_by_version]
+            .filter((version) => version !== undefined)
+            .reduce((newest, candidate) => {
+            if (newest === undefined || isLaneStoreVersionNewer(candidate, newest))
+                return candidate;
+            return newest;
+        }, undefined);
+        return storedVersion !== undefined && isLaneStoreVersionNewer(storedVersion, CLI_VERSION)
+            ? [{
+                    code: "lane_store_newer_cli",
+                    lane_id: lane.lane_id,
+                    stored_version: storedVersion,
+                    running_version: CLI_VERSION,
+                    upgrade_command: LANE_STORE_UPGRADE_COMMAND,
+                    message: `Lane ${lane.lane_id} has a local or owner-host copy last written by hq-cli ${storedVersion}, newer than running hq-cli ${CLI_VERSION}. Upgrade before writing.`
+                }]
+            : [];
+    });
+    const teams = readTeamInputs(root, company, selectedProjects, laneRecords);
+    const questionRecords = readCompanyQuestions(root, company, projectFilter);
+    const trackerRecords = await readTrackerCheckRecords(root, company, selectedProjects);
+    const directiveTeams = [...directiveProjects.values()].map((project) => ({
+        team: project.team,
+        ...(project.leadLaneId === undefined ? {} : { lead_lane_id: project.leadLaneId }),
+    }));
+    const checks = evaluateTrackerChecks({
+        now,
+        thresholds: loadLanesConfig(root).tracker.checks,
+        questions: questionRecords,
+        teams,
+        ...trackerRecords,
+        directives: trackerRecords.directives,
+        directive_teams: directiveTeams,
+    });
+    const orphanedLanes = orphanFindings(root, company, now, minAgeMinutes, deps, projectFilter);
+    checks.push({
+        id: "orphaned_lane",
+        result: orphanedLanes.length === 0 ? "ok" : "failing",
+        items: orphanedLanes.map((finding) => ({
+            id: finding.lane_id,
+            reason: finding.reason,
+            company_source: finding.company_source,
+            senior: finding.senior,
+            senior_state: finding.senior_state,
+            age_minutes: finding.age_minutes,
+            account: finding.account,
+            host: finding.host,
+        })),
+    });
+    return {
+        ok: true,
+        company: company.slug,
+        generated_at: now.toISOString(),
+        ...(warnings.length === 0 ? {} : { warnings }),
+        ...(projectErrors.length === 0 ? {} : { project_errors: projectErrors }),
+        checks,
+    };
+}
+async function orphanReport(root, company, now, minAgeMinutes, userIdleHours, deps, options) {
+    const reason = options.reason?.trim();
+    if (options.stop && !reason) {
+        fail("orphan_stop_reason_required", "--stop requires a non-empty --reason", {});
+    }
+    if (!options.stop && options.reason !== undefined) {
+        fail("orphan_reason_requires_stop", "--reason can only be used with --stop", {});
+    }
+    if (reason !== undefined)
+        assertNoSecretText("stop reason", reason);
+    const unscoped = options.unscoped === true;
+    const orphans = orphanFindings(root, company, now, minAgeMinutes, deps, undefined, unscoped, userIdleHours);
+    const output = (action, stopped) => {
+        if (options.human) {
+            const companyText = unscoped ? "unscoped" : company?.slug ?? "unknown";
+            console.log(`company: ${companyText}`);
+            console.log("lane_id\tsenior\tsenior_state\treason\tcompany_source\tage_minutes\taccount\thost");
+            for (const finding of orphans) {
+                console.log([
+                    finding.lane_id,
+                    `${finding.senior.kind}:${finding.senior.id ?? ""}`,
+                    finding.senior_state,
+                    finding.reason,
+                    finding.company_source,
+                    finding.age_minutes,
+                    finding.account ?? "",
+                    `${finding.host.kind}:${finding.host.id}`,
+                ].join("\t"));
+            }
+            if (orphans.length === 0)
+                console.log("(none)");
+            if (stopped !== undefined) {
+                console.log("stopped:");
+                for (const entry of stopped)
+                    console.log(`${entry.lane_id}\t${entry.state}`);
+            }
+            return;
+        }
+        console.log(JSON.stringify({
+            ok: true,
+            action,
+            company: company?.slug ?? null,
+            ...(unscoped ? { unscoped: true } : {}),
+            generated_at: now.toISOString(),
+            min_age_minutes: minAgeMinutes,
+            user_idle_hours: userIdleHours,
+            ...(reason === undefined ? {} : { reason }),
+            orphans,
+            ...(stopped === undefined ? {} : { stopped }),
+        }, null, 2));
+    };
+    if (!options.stop) {
+        output("orphans");
+        return;
+    }
+    if (!deps.stopLane)
+        fail("orphan_stop_unavailable", "The normal lane stop path is unavailable", {});
+    const stopped = [];
+    for (const finding of orphans) {
+        const fresh = orphanFindings(root, company, deps.now(), minAgeMinutes, deps, undefined, unscoped, userIdleHours)
+            .find((candidate) => candidate.lane_id === finding.lane_id);
+        if (!fresh)
+            continue;
+        await deps.stopLane(finding.lane_id, reason);
+        stopped.push({ lane_id: finding.lane_id, state: readLane(root, finding.lane_id).state });
+    }
+    output("orphans.stop", stopped);
+}
+export function registerLaneChecksCommand(parent, deps, wrap) {
+    parent.command("checks")
+        .description("Evaluate tracker and lane health checks")
+        .option("--company <slug>", "Select the company by slug")
+        .option("--project <slug>", "Limit checks to one company project")
+        .option("--min-age <minutes>", "Minimum orphan lane age in minutes (default: 30)")
+        .action(wrap(async (options) => {
+        const company = await resolveTrackerCompany(deps, options.company);
+        const root = deps.hqRoot();
+        const projectFilter = options.project === undefined ? undefined : validSegment(options.project, "project");
+        const minAgeMinutes = parseOrphanMinAge(options.minAge);
+        const allProjects = loadProjectMappings(root, company.slug);
+        const ambiguous = ambiguousProjectMappings([...allProjects.values()]);
+        const selectedAll = projectFilter === undefined ? [...allProjects.values()] : [...allProjects.values()].filter((mapping) => mapping.projectId === projectFilter);
+        const projectErrors = [...ambiguous].filter(([projectId]) => projectFilter === undefined || projectId === projectFilter).map(([project_id, teams]) => ({
+            project_id,
+            code: "tracker_checks_mapping_ambiguous",
+            teams,
+            message: "Team story prefixes overlap for this project",
+        }));
+        const projects = new Map(selectedAll.filter((mapping) => !ambiguous.has(mapping.projectId)).map((mapping, index) => [`${mapping.projectId}:${mapping.team}:${index}`, mapping]));
+        const directiveProjects = new Map([...allProjects.values()].filter((mapping) => !ambiguous.has(mapping.projectId)).map((mapping, index) => [`${mapping.projectId}:${mapping.team}:${index}`, mapping]));
+        const report = await checkReport(root, company, projects, directiveProjects, projectFilter, minAgeMinutes, deps.now(), deps, projectErrors);
+        console.log(JSON.stringify(report, null, 2));
+        if (report.checks.some((item) => item.result === "failing") || projectErrors.length > 0)
+            process.exitCode = 2;
+    }));
+    parent.command("orphans")
+        .description("Report lanes whose senior has ended or gone idle")
+        .option("--company <slug>", "Select the company by slug")
+        .option("--min-age <minutes>", "Minimum orphan lane age in minutes (default: 30)")
+        .option("--user-idle-hours <hours>", "Idle hours for user-senior lanes (default: 72)")
+        .option("--unscoped", "Report candidates whose company cannot be resolved")
+        .option("--stop", "Stop the reported lanes through their normal owner path")
+        .option("--reason <text>", "Required audit reason when --stop is set")
+        .option("--json", "Print machine-readable JSON")
+        .option("--human", "Print a human-readable table")
+        .action(wrap(async (options) => {
+        if (options.unscoped && options.company !== undefined) {
+            fail("orphan_scope_conflict", "--unscoped cannot be combined with --company", {});
+        }
+        if (options.human && options.json) {
+            fail("conflicting_output_format", "Choose either --json or --human output", {});
+        }
+        const company = options.unscoped ? null : await deps.resolveCompany(options.company);
+        const root = deps.hqRoot();
+        const minAgeMinutes = parseOrphanMinAge(options.minAge);
+        const userIdleHours = parseOrphanUserIdleHours(options.userIdleHours);
+        await orphanReport(root, company, deps.now(), minAgeMinutes, userIdleHours, deps, options);
+    }));
+}
+//# sourceMappingURL=lanes-checks.js.map