@indigoai-us/hq-cli 5.197.0 → 5.198.0

package/dist/commands/lanes-tracker.js

@@ -0,0 +1,420 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { LanesError } from "../lib/lanes/errors.js";
+import { resolveProjectStoryLedger } from "../lib/lanes/story-ledger.js";
+import { assertNoSecretText } from "../lib/lanes/text-scan.js";
+import { createLocalTrackerStore } from "../lib/lanes/tracker-store.js";
+import { peekIdToken } from "../utils/id-token.js";
+export const LANES_TRACKER_FLAG = "lanes.tracker";
+export const LANES_TRACKER_MESH_FLAG = "lanes.tracker-mesh";
+const MAX_POLICY_PATH_BYTES = 4096;
+function fail(error, message, details = {}) {
+    throw new LanesError(error, message, details);
+}
+function validSegment(value, label) {
+    const normalized = value.trim();
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(normalized) || normalized === "." || normalized === "..") {
+        return fail("tracker_input_invalid", `${label} must be a safe path segment`, { field: label, value });
+    }
+    return normalized;
+}
+function requiredText(field, text) {
+    if (!text.trim())
+        fail("tracker_input_invalid", `${field} must not be empty`, { field });
+    return text;
+}
+function checkedText(field, text, maxBytes) {
+    requiredText(field, text);
+    if (maxBytes !== undefined && Buffer.byteLength(text, "utf8") > maxBytes) {
+        fail("tracker_input_too_long", `${field} exceeds the maximum length`, { field, max_length: maxBytes });
+    }
+    assertNoSecretText(field, text);
+    return text;
+}
+function readProjectCompany(prdPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(prdPath, "utf8"));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            fail("tracker_project_not_found", "Project prd.json was not found for this company", { path: prdPath });
+        fail("tracker_project_invalid", "Project prd.json must contain valid JSON", { path: prdPath });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return fail("tracker_project_invalid", "Project prd.json must contain a JSON object", { path: prdPath });
+    }
+    const object = parsed;
+    const metadata = object.metadata && typeof object.metadata === "object" && !Array.isArray(object.metadata)
+        ? object.metadata
+        : undefined;
+    const raw = object.company ?? metadata?.company;
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === "string")
+        return raw;
+    if (typeof raw === "object" && !Array.isArray(raw)) {
+        const slug = raw.slug;
+        if (typeof slug === "string")
+            return slug;
+    }
+    return fail("tracker_project_invalid", "Project company metadata must name a company slug", { path: prdPath });
+}
+async function target(deps, options) {
+    const company = await deps.resolveCompany(options.company);
+    if (!company.slug)
+        fail("tracker_company_unresolved", "The active HQ company could not be resolved", {});
+    // Check the feature gate before inspecting the project path. A disabled flag
+    // reveals neither project existence nor any local tracker data.
+    if (!await deps.trackerEnabled(company)) {
+        fail("tracker_disabled", "hq lanes tracker commands require the lanes.tracker flag", { company: company.slug });
+    }
+    if (await deps.trackerMeshEnabled(company)) {
+        fail("tracker_mesh_unavailable", "Work Mesh tracker storage is not available in this CLI version", { company: company.slug });
+    }
+    const project = validSegment(options.project, "project");
+    const ledger = resolveProjectStoryLedger(deps.hqRoot(), project, company.slug);
+    const projectCompany = readProjectCompany(ledger.path);
+    if (projectCompany !== null && projectCompany !== company.slug) {
+        fail("tracker_company_mismatch", "Project company does not match the active HQ company", {
+            active_company: company.slug,
+            project_company: projectCompany,
+            project_id: project,
+        });
+    }
+    const directory = path.dirname(ledger.path);
+    let realDirectory;
+    try {
+        realDirectory = fs.realpathSync(directory);
+    }
+    catch (err) {
+        fail("tracker_project_not_found", "Project directory was not found for this company", {
+            project_id: project,
+            filesystem_code: err.code ?? "unknown",
+        });
+    }
+    const expectedRoot = fs.realpathSync(path.join(deps.hqRoot(), "companies", company.slug, "projects"));
+    if (!realDirectory.startsWith(`${expectedRoot}${path.sep}`)) {
+        fail("tracker_company_mismatch", "Project directory resolves outside the active HQ company", {
+            active_company: company.slug,
+            project_id: project,
+        });
+    }
+    return {
+        company,
+        project,
+        store: (deps.store ?? ((dir) => createLocalTrackerStore(dir, deps.now)))(realDirectory),
+    };
+}
+function requireActor(deps) {
+    const actor = deps.actor()?.trim();
+    if (!actor)
+        fail("tracker_identity_unavailable", "Cannot record approval without a signed-in HQ identity", {});
+    return actor;
+}
+function numberValue(raw, field) {
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        return fail("tracker_input_invalid", `${field} must be a finite number`, { field });
+    return value;
+}
+function parseKr(raw) {
+    const match = /^(.+)=([a-zA-Z0-9][a-zA-Z0-9._-]{0,127}):(-?(?:\d+(?:\.\d*)?|\.\d+))$/.exec(raw);
+    if (!match)
+        fail("tracker_key_result_invalid", "Key result must be <text>=<kpi-id>:<target>", {});
+    return { text: match[1].trim(), kpi_id: validSegment(match[2], "kpi-id"), target: numberValue(match[3], "key-result target") };
+}
+function validDate(raw) {
+    let normalized;
+    try {
+        normalized = new Date(`${raw}T00:00:00.000Z`).toISOString().slice(0, 10);
+    }
+    catch {
+        normalized = undefined;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw) || normalized !== raw) {
+        return fail("tracker_date_invalid", "Date must be a valid YYYY-MM-DD value", { field: "date" });
+    }
+    return raw;
+}
+function validTimestamp(raw) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})$/.exec(raw);
+    if (!match)
+        return fail("tracker_date_invalid", "KPI --at must be an ISO 8601 timestamp with a timezone", { field: "at" });
+    const [, year, month, day, hour, minute, second = "00", fraction = "", zone] = match;
+    const date = `${year}-${month}-${day}`;
+    let calendarDate;
+    try {
+        calendarDate = new Date(`${date}T00:00:00.000Z`).toISOString().slice(0, 10);
+    }
+    catch {
+        calendarDate = undefined;
+    }
+    if (calendarDate !== date || Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59) {
+        return fail("tracker_date_invalid", "KPI --at must be an ISO 8601 timestamp with a timezone", { field: "at" });
+    }
+    let offsetMinutes = 0;
+    if (zone !== "Z") {
+        const offset = /^([+-])(\d{2}):(\d{2})$/.exec(zone);
+        const offsetHours = Number(offset?.[2]);
+        const offsetRemainder = Number(offset?.[3]);
+        if (!offset || offsetHours > 14 || offsetRemainder > 59 || (offsetHours === 14 && offsetRemainder !== 0)) {
+            return fail("tracker_date_invalid", "KPI --at must be an ISO 8601 timestamp with a timezone", { field: "at" });
+        }
+        const sign = offset[1] === "+" ? 1 : -1;
+        offsetMinutes = sign * (offsetHours * 60 + offsetRemainder);
+    }
+    const localTimeAsUtc = new Date(`${date}T${hour}:${minute}:${second}.${fraction.padEnd(3, "0")}Z`);
+    const expectedEpoch = localTimeAsUtc.getTime() - offsetMinutes * 60_000;
+    const parsed = new Date(raw);
+    if (!Number.isFinite(expectedEpoch) || !Number.isFinite(parsed.getTime()) || parsed.getTime() !== expectedEpoch) {
+        return fail("tracker_date_invalid", "KPI --at must be an ISO 8601 timestamp with a timezone", { field: "at" });
+    }
+    const roundTripped = new Date(parsed.toISOString());
+    if (roundTripped.getTime() !== expectedEpoch) {
+        return fail("tracker_date_invalid", "KPI --at must be an ISO 8601 timestamp with a timezone", { field: "at" });
+    }
+    return parsed;
+}
+function addProjectOptions(command) {
+    return command
+        .requiredOption("--project <slug>", "HQ team project slug")
+        .option("--company <slug>", "Select the company by slug");
+}
+function createRecord(store, kind, company, project, fields) {
+    return store.create({ kind, id: randomUUID(), company, project_id: project, ...fields });
+}
+export function registerLaneTrackerCommands(parent, deps, wrap) {
+    const blocker = parent.command("blocker").description("Record and manage project blockers");
+    addProjectOptions(blocker.command("open").description("Open a blocker"))
+        .requiredOption("--story <id>", "Blocked story id")
+        .requiredOption("--what <text>", "What is blocked")
+        .requiredOption("--waiting-on <text>", "Who or what is needed")
+        .requiredOption("--next-step <text>", "Next action")
+        .action(wrap(async (options) => {
+        const { company, project, store } = await target(deps, options);
+        if (!options.story.trim())
+            fail("tracker_input_invalid", "story must not be empty", { field: "story" });
+        for (const [field, value] of [["what", options.what], ["waiting_on", options.waitingOn], ["next_step", options.nextStep]])
+            checkedText(field, value);
+        const record = createRecord(store, "blocker", company.slug, project, {
+            story_id: options.story.trim(), what: options.what, waiting_on: options.waitingOn,
+            next_step: options.nextStep, opened_at: deps.now().toISOString(), resolved_at: null, resolution: null,
+        });
+        console.log(JSON.stringify({ ok: true, action: "blocker.open", record }, null, 2));
+    }));
+    addProjectOptions(blocker.command("update").description("Update a blocker").argument("<blocker-id>", "Blocker id"))
+        .option("--waiting-on <text>", "Who or what is needed")
+        .option("--next-step <text>", "Next action")
+        .action(wrap(async (id, options) => {
+        const { store } = await target(deps, options);
+        if (options.waitingOn === undefined && options.nextStep === undefined)
+            fail("tracker_update_empty", "Supply --waiting-on or --next-step", {});
+        if (options.waitingOn !== undefined)
+            checkedText("waiting_on", options.waitingOn);
+        if (options.nextStep !== undefined)
+            checkedText("next_step", options.nextStep);
+        const current = store.read("blocker", id);
+        if (!current)
+            fail("tracker_record_not_found", `Tracker blocker record ${id} was not found`, { kind: "blocker", id });
+        if (current.resolved_at !== null)
+            fail("tracker_already_resolved", "Blocker is already resolved", { id });
+        const record = store.update("blocker", id, current.version, (value) => ({
+            ...value,
+            ...(options.waitingOn === undefined ? {} : { waiting_on: options.waitingOn }),
+            ...(options.nextStep === undefined ? {} : { next_step: options.nextStep }),
+        }));
+        console.log(JSON.stringify({ ok: true, action: "blocker.update", record }, null, 2));
+    }));
+    addProjectOptions(blocker.command("resolve").description("Resolve a blocker").argument("<blocker-id>", "Blocker id"))
+        .requiredOption("--resolution <text>", "Resolution details")
+        .action(wrap(async (id, options) => {
+        const { store } = await target(deps, options);
+        checkedText("resolution", options.resolution);
+        const current = store.read("blocker", id);
+        if (!current)
+            fail("tracker_record_not_found", `Tracker blocker record ${id} was not found`, { kind: "blocker", id });
+        if (current.resolved_at !== null)
+            fail("tracker_already_resolved", "Blocker is already resolved", { id });
+        const record = store.update("blocker", id, current.version, (value) => ({ ...value, resolved_at: deps.now().toISOString(), resolution: options.resolution }));
+        console.log(JSON.stringify({ ok: true, action: "blocker.resolve", record }, null, 2));
+    }));
+    addProjectOptions(blocker.command("list").description("List blockers")).option("--all", "Include resolved blockers")
+        .action(wrap(async (options) => {
+        const { store } = await target(deps, options);
+        const records = store.list("blocker").filter((record) => options.all || record.resolved_at === null);
+        console.log(JSON.stringify({ ok: true, action: "blocker.list", records }, null, 2));
+    }));
+    const kpi = parent.command("kpi").description("Define KPIs and record values");
+    addProjectOptions(kpi.command("define").description("Define a proposed KPI"))
+        .requiredOption("--name <text>", "KPI name")
+        .requiredOption("--definition <text>", "Definition or query")
+        .requiredOption("--unit <unit>", "Measurement unit")
+        .requiredOption("--target <number>", "Target value")
+        .requiredOption("--direction <direction>", "up | down")
+        .action(wrap(async (options) => {
+        const { company, project, store } = await target(deps, options);
+        if (options.direction !== "up" && options.direction !== "down")
+            fail("tracker_direction_invalid", "KPI direction must be up or down", { direction: options.direction });
+        checkedText("name", options.name);
+        checkedText("definition", options.definition);
+        requiredText("unit", options.unit);
+        const record = createRecord(store, "kpi", company.slug, project, {
+            name: options.name, definition: options.definition, unit: options.unit,
+            target: numberValue(options.target, "target"), direction: options.direction,
+            status: "proposed", approved_by: null, approved_at: null, values: [],
+        });
+        console.log(JSON.stringify({ ok: true, action: "kpi.define", record }, null, 2));
+    }));
+    addProjectOptions(kpi.command("record").description("Record a KPI value").argument("<kpi-id>", "KPI id"))
+        .requiredOption("--value <number>", "Observed value")
+        .requiredOption("--source <text>", "Value source")
+        .option("--at <iso>", "Observation time")
+        .action(wrap(async (id, options) => {
+        const { store } = await target(deps, options);
+        checkedText("source", options.source);
+        const value = numberValue(options.value, "value");
+        const at = options.at === undefined ? deps.now() : validTimestamp(options.at);
+        const current = store.read("kpi", id);
+        if (!current)
+            fail("tracker_record_not_found", `Tracker KPI record ${id} was not found`, { kind: "kpi", id });
+        const values = current.values;
+        if (!Array.isArray(values))
+            fail("tracker_record_invalid", "KPI values must be an array", { id });
+        const record = store.update("kpi", id, current.version, (record) => ({ ...record, values: [...values, { at: at.toISOString(), value, source: options.source }] }));
+        console.log(JSON.stringify({ ok: true, action: "kpi.record", record }, null, 2));
+    }));
+    addProjectOptions(kpi.command("approve").description("Approve a KPI proposal").argument("<kpi-id>", "KPI id"))
+        .action(wrap(async (id, options) => {
+        const { store } = await target(deps, options);
+        const current = store.read("kpi", id);
+        if (!current)
+            fail("tracker_record_not_found", `Tracker KPI record ${id} was not found`, { kind: "kpi", id });
+        const record = store.update("kpi", id, current.version, (value) => {
+            if (value.status === "approved")
+                fail("tracker_already_approved", "KPI is already approved", { id });
+            return { ...value, status: "approved", approved_by: requireActor(deps), approved_at: deps.now().toISOString() };
+        });
+        console.log(JSON.stringify({ ok: true, action: "kpi.approve", record }, null, 2));
+    }));
+    addProjectOptions(kpi.command("list").description("List KPIs")).action(wrap(async (options) => {
+        const { store } = await target(deps, options);
+        console.log(JSON.stringify({ ok: true, action: "kpi.list", records: store.list("kpi") }, null, 2));
+    }));
+    const okr = parent.command("okr").description("Set and approve OKRs");
+    addProjectOptions(okr.command("set").description("Create a proposed OKR"))
+        .requiredOption("--objective <text>", "Objective")
+        .requiredOption("--period <period>", "Planning period")
+        .requiredOption("--key-result <text=kpi-id:target>", "Key result", (value, previous = []) => previous.concat(value))
+        .action(wrap(async (options) => {
+        const { company, project, store } = await target(deps, options);
+        checkedText("objective", options.objective);
+        requiredText("period", options.period);
+        if (!Array.isArray(options.keyResult) || options.keyResult.length === 0)
+            fail("tracker_key_result_invalid", "At least one --key-result is required", {});
+        const keyResults = options.keyResult.map(parseKr);
+        for (const keyResult of keyResults)
+            checkedText("key_result", keyResult.text);
+        for (const keyResult of keyResults) {
+            if (!store.read("kpi", keyResult.kpi_id)) {
+                fail("tracker_kpi_not_found", `Referenced KPI ${keyResult.kpi_id} was not found in this project`, { kpi_id: keyResult.kpi_id, project_id: project });
+            }
+        }
+        const record = createRecord(store, "okr", company.slug, project, {
+            objective: options.objective, period: options.period,
+            key_results: keyResults.map((value) => ({ kr_id: randomUUID(), ...value })),
+            status: "proposed", approved_by: null, approved_at: null,
+        });
+        console.log(JSON.stringify({ ok: true, action: "okr.set", record }, null, 2));
+    }));
+    addProjectOptions(okr.command("approve").description("Approve an OKR proposal").argument("<okr-id>", "OKR id"))
+        .action(wrap(async (id, options) => {
+        const { store } = await target(deps, options);
+        const current = store.read("okr", id);
+        if (!current)
+            fail("tracker_record_not_found", `Tracker OKR record ${id} was not found`, { kind: "okr", id });
+        const record = store.update("okr", id, current.version, (value) => {
+            if (value.status === "approved")
+                fail("tracker_already_approved", "OKR is already approved", { id });
+            return { ...value, status: "approved", approved_by: requireActor(deps), approved_at: deps.now().toISOString() };
+        });
+        console.log(JSON.stringify({ ok: true, action: "okr.approve", record }, null, 2));
+    }));
+    addProjectOptions(okr.command("list").description("List OKRs")).action(wrap(async (options) => {
+        const { store } = await target(deps, options);
+        console.log(JSON.stringify({ ok: true, action: "okr.list", records: store.list("okr") }, null, 2));
+    }));
+    const directive = parent.command("directive").description("Record directives and acknowledgements");
+    addProjectOptions(directive.command("record").description("Record a directive"))
+        .requiredOption("--text <text>", "Verbatim directive")
+        .requiredOption("--date <yyyy-mm-dd>", "Directive date")
+        .requiredOption("--source-url <url>", "Source URL")
+        .requiredOption("--team <slug>", "Affected team (repeatable)", (value, previous = []) => previous.concat(value))
+        .option("--policy-path <path>", "Related policy path")
+        .action(wrap(async (options) => {
+        const { company, project, store } = await target(deps, options);
+        checkedText("text", options.text);
+        checkedText("source_url", options.sourceUrl);
+        const policyPath = options.policyPath === undefined
+            ? null
+            : checkedText("policy_path", options.policyPath, MAX_POLICY_PATH_BYTES);
+        const teams = (options.team ?? []).map((team) => validSegment(team, "team"));
+        if (teams.length === 0)
+            fail("tracker_input_invalid", "At least one --team is required", { field: "team" });
+        let url;
+        try {
+            url = new URL(options.sourceUrl);
+        }
+        catch {
+            return fail("tracker_source_url_invalid", "Source URL must be an absolute URL", {});
+        }
+        if (url.protocol !== "https:" && url.protocol !== "http:")
+            fail("tracker_source_url_invalid", "Source URL must use HTTP or HTTPS", {});
+        const record = createRecord(store, "directive", company.slug, project, {
+            text: options.text, date: validDate(options.date), source_url: options.sourceUrl,
+            teams: [...new Set(teams)].sort(), policy_path: policyPath, acknowledgements: [],
+        });
+        console.log(JSON.stringify({ ok: true, action: "directive.record", record }, null, 2));
+    }));
+    addProjectOptions(directive.command("ack").description("Acknowledge a directive").argument("<directive-id>", "Directive id"))
+        .requiredOption("--team <slug>", "Acknowledging team")
+        .requiredOption("--lane <lane-id>", "Acknowledging lane id")
+        .action(wrap(async (id, options) => {
+        const { store } = await target(deps, options);
+        const team = validSegment(options.team, "team");
+        const lane = validSegment(options.lane, "lane");
+        const current = store.read("directive", id);
+        if (!current)
+            fail("tracker_record_not_found", `Tracker directive record ${id} was not found`, { kind: "directive", id });
+        const teams = current.teams;
+        const acknowledgements = current.acknowledgements;
+        if (!Array.isArray(teams) || !teams.includes(team))
+            fail("tracker_team_not_targeted", "Team is not listed on this directive", { id, team });
+        if (!Array.isArray(acknowledgements))
+            fail("tracker_record_invalid", "Directive acknowledgements must be an array", { id });
+        const record = store.update("directive", id, current.version, (value) => ({
+            ...value,
+            acknowledgements: [...acknowledgements.filter((ack) => !(ack && typeof ack === "object" && ack.team === team && ack.lane_id === lane)), { team, lane_id: lane, at: deps.now().toISOString() }],
+        }));
+        console.log(JSON.stringify({ ok: true, action: "directive.ack", record }, null, 2));
+    }));
+    addProjectOptions(directive.command("list").description("List directives")).action(wrap(async (options) => {
+        const { store } = await target(deps, options);
+        console.log(JSON.stringify({ ok: true, action: "directive.list", records: store.list("directive") }, null, 2));
+    }));
+}
+export function defaultTrackerActor() {
+    const tokens = loadCachedTokens();
+    if (!tokens)
+        return null;
+    const claims = peekIdToken(tokens.idToken);
+    const uid = claims["custom:entityUid"];
+    if (typeof uid === "string" && uid.trim())
+        return uid.trim();
+    const sub = claims.sub;
+    return typeof sub === "string" && sub.trim() ? sub.trim() : null;
+}
+//# sourceMappingURL=lanes-tracker.js.map

package/dist/commands/lanes.d.ts

@@ -88,6 +88,12 @@ export interface LanesCommandDeps {
     withGrantHireLocks?: typeof withLaneHireLocks;
     /** Test seam for the Claude account-balancing gate. */
     laneClaudeAccountBalanceEnabled?: (company?: LaneCompanyRef | null) => boolean | Promise<boolean>;
+    /** Test seam for the hq-flags gated tracker commands. */
+    laneTrackerEnabled?: (company: LaneCompanyRef) => boolean | Promise<boolean>;
+    /** The local-only PR 2 implementation refuses if mesh storage is enabled. */
+    laneTrackerMeshEnabled?: (company: LaneCompanyRef) => boolean | Promise<boolean>;
+    /** Test seam for recording approvals against the active identity. */
+    trackerActor?: () => string | null;
 }
 export declare const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
 export declare function parseSeniorRef(raw: string): SeniorRef;

package/dist/commands/lanes.js

@@ -17,6 +17,7 @@ import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
+import { defaultTrackerActor, LANES_TRACKER_FLAG, LANES_TRACKER_MESH_FLAG, registerLaneTrackerCommands, } from "./lanes-tracker.js";
 import { createOutpostHireGrantContext, parseOutpostHireGrantContext, sameHireGrantSenior, } from "../lib/lanes/hire-grant-dispatch.js";
 import { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity, resolveAdmissionHost, } from "../lib/lanes/admission-host.js";
 export { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity } from "../lib/lanes/admission-host.js";
@@ -62,6 +63,12 @@ function defaultLaneClaudeAccountBalanceEnabled(company) {
     // behavior, matching the lane hire-grants gate.
     return readLanesRegistryFlag(CLAUDE_ACCOUNT_BALANCE_FLAG, { company });
 }
+function defaultLaneTrackerEnabled(company) {
+    return readLanesRegistryFlag(LANES_TRACKER_FLAG, { company });
+}
+function defaultLaneTrackerMeshEnabled(company) {
+    return readLanesRegistryFlag(LANES_TRACKER_MESH_FLAG, { company });
+}
 function defaultLaneHireGrantsEnabled(company) {
     return readLanesRegistryFlag(LANE_HIRE_GRANTS_FLAG, { company });
 }
@@ -264,6 +271,9 @@ function resolveDeps(deps = {}) {
         isSsmOwnerDispatch: deps.isSsmOwnerDispatch ?? (() => isSsmRunCommandProcess()),
         withGrantHireLocks: deps.withGrantHireLocks ?? withLaneHireLocks,
         laneClaudeAccountBalanceEnabled: deps.laneClaudeAccountBalanceEnabled ?? defaultLaneClaudeAccountBalanceEnabled,
+        laneTrackerEnabled: deps.laneTrackerEnabled ?? defaultLaneTrackerEnabled,
+        laneTrackerMeshEnabled: deps.laneTrackerMeshEnabled ?? defaultLaneTrackerMeshEnabled,
+        trackerActor: deps.trackerActor ?? defaultTrackerActor,
     };
 }
 function livenessDepsFromCtx(ctx) {
@@ -7299,6 +7309,14 @@ export function registerLanesCommand(parent, deps = {}) {
     const lanes = parent
         .command("lanes", { hidden: true })
         .description("Create, supervise, and steer worker lanes; routed decision queue");
+    registerLaneTrackerCommands(lanes, {
+        hqRoot: ctx.hqRoot,
+        resolveCompany: ctx.resolveCompany,
+        trackerEnabled: ctx.laneTrackerEnabled,
+        trackerMeshEnabled: ctx.laneTrackerMeshEnabled,
+        now: ctx.now,
+        actor: ctx.trackerActor,
+    }, wrap);
     registerOutpostPrunerCommand(lanes);
     const noStoryOption = new Option("--no-story <reason>", "Create a lane without a story and record why");
     noStoryOption.attributeName = () => "noStory";

package/dist/lib/bot/inflight.d.ts

@@ -93,6 +93,18 @@ export interface InflightTurn {
      * RECOVERY_ATTEMPT_LIMIT and says so once (run.ts).
      */
     recoveryFailures?: number;
+    /**
+     * True when the interrupted turn was a "silenceable" one: an unmentioned
+     * room message nobody asked the bot to answer. On recovery a silenceable
+     * turn with no saved reply is acked silently — a "I didn't finish that —
+     * I was restarted…" notice in a public room the bot was not addressed in
+     * is noise, and (2026-09-25) had two bots posting it in a channel where
+     * neither had been @-mentioned. A silenceable marker WITH a saved
+     * `reply` still posts: that was a real answer the model produced and only
+     * delivery failed. Absent (older marker) → recover posts the notice, as
+     * before.
+     */
+    silenceable?: boolean;
 }
 export declare function botInflightPath(dir: string): string;
 /** Every turn that was in progress, oldest first. */

package/dist/lib/bot/run.js

@@ -648,10 +648,15 @@ export async function runBot(deps) {
      */
     const runTurnWithProgress = async (args) => {
         const { messageId } = args.marker;
-        writeInflight(dir, { v: 1, ...args.marker, startedAt: now().toISOString() });
+        const silenceable = args.silenceable === true;
+        writeInflight(dir, {
+            v: 1,
+            ...args.marker,
+            startedAt: now().toISOString(),
+            ...(silenceable ? { silenceable: true } : {}),
+        });
         let running = true;
         let posted = 0;
-        const silenceable = args.silenceable === true;
         const makeSendFn = (fn) => async (body) => {
             try {
                 await fn(body);
@@ -937,6 +942,20 @@ export async function runBot(deps) {
             clearInflight(dir, marker.messageId);
             return true;
         }
+        // An unmentioned room turn (silenceable) that never produced a saved
+        // reply: the person never asked the bot to answer. Posting "I didn't
+        // finish that — I was restarted…" into that room is noise (2026-09-25:
+        // two bots posted the notice in a channel where neither was mentioned).
+        // Ack and clear silently; a saved `reply` still posts below because a
+        // real answer that only failed delivery is worth keeping.
+        if (!isKickoff &&
+            marker.silenceable === true &&
+            !marker.jobId &&
+            (marker.reply === undefined || marker.reply.trim() === "")) {
+            log("info", `recovered unmentioned room turn ${marker.messageId} silently (no saved reply); not posting a restart notice`);
+            await closeMarker(marker, isKickoff);
+            return true;
+        }
         const parts = marker.replyParts ?? splitBody(recoveryBody(marker));
         const from = marker.replyParts ? Math.min(Math.max(0, marker.replyPartsDelivered ?? 0), parts.length) : 0;
         try {

package/dist/lib/bot/runtime/messages-stream.d.ts

@@ -31,6 +31,26 @@ export declare function messagesStreamEvents(line: string): RuntimeStreamEvent[]
  * RuntimeError for an error result, or when there is nothing usable.
  */
 export declare function messagesStreamResult(stdout: string, runtimeName: string): RuntimeTurnResult;
-/** The error text of an `is_error` result event, if the stream has one. */
+/**
+ * The error text of an `is_error` result event, if the stream has one.
+ *
+ * Also handles the case grok 0.2.56+ produces on some non-zero exits: the
+ * whole stdout is one pretty-printed JSON object (a `result` envelope
+ * spanning many lines) rather than NDJSON. The per-line parser sees only
+ * `{` / `"key": …` / `}` fragments and cannot recover the fields, so
+ * `stderrExcerpt(stdout)` ended up logging the tail of the pretty JSON —
+ * "…costUsdTicks…numTurns…" — instead of the actual error text
+ * (observed 2026-09-25 in sheister's log). We try a whole-stdout JSON parse
+ * as a fallback and pull the real error string out of the envelope.
+ */
 export declare function messagesStreamFailure(stdout: string): string | undefined;
+/**
+ * Whole stdout parsed as ONE JSON object (grok 0.2.56+ pretty-printed
+ * result envelope). Pulls the error text out of the fields the runtimes
+ * actually populate: `error.message` / `error`, then `result` when
+ * `is_error` is set, then `subtype` when it isn't "success". Returns
+ * undefined when there is nothing useful to say — the caller falls back
+ * to its own default.
+ */
+export declare function prettyJsonFailure(stdout: string): string | undefined;
 //# sourceMappingURL=messages-stream.d.ts.map

package/dist/lib/bot/runtime/messages-stream.js

@@ -127,7 +127,18 @@ function grokTokenStreamResult(stdout, runtimeName) {
     }
     return saw ? { text, sessionId } : null;
 }
-/** The error text of an `is_error` result event, if the stream has one. */
+/**
+ * The error text of an `is_error` result event, if the stream has one.
+ *
+ * Also handles the case grok 0.2.56+ produces on some non-zero exits: the
+ * whole stdout is one pretty-printed JSON object (a `result` envelope
+ * spanning many lines) rather than NDJSON. The per-line parser sees only
+ * `{` / `"key": …` / `}` fragments and cannot recover the fields, so
+ * `stderrExcerpt(stdout)` ended up logging the tail of the pretty JSON —
+ * "…costUsdTicks…numTurns…" — instead of the actual error text
+ * (observed 2026-09-25 in sheister's log). We try a whole-stdout JSON parse
+ * as a fallback and pull the real error string out of the envelope.
+ */
 export function messagesStreamFailure(stdout) {
     let reason;
     for (const line of stdout.split("\n")) {
@@ -137,6 +148,47 @@ export function messagesStreamFailure(stdout) {
         if (ev?.type === "error" && typeof ev.message === "string" && ev.message.trim())
             reason = ev.message.trim();
     }
-    return reason;
+    if (reason)
+        return reason;
+    return prettyJsonFailure(stdout);
+}
+/**
+ * Whole stdout parsed as ONE JSON object (grok 0.2.56+ pretty-printed
+ * result envelope). Pulls the error text out of the fields the runtimes
+ * actually populate: `error.message` / `error`, then `result` when
+ * `is_error` is set, then `subtype` when it isn't "success". Returns
+ * undefined when there is nothing useful to say — the caller falls back
+ * to its own default.
+ */
+export function prettyJsonFailure(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    let ev = null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            ev = parsed;
+    }
+    catch {
+        return undefined;
+    }
+    if (!ev)
+        return undefined;
+    const err = ev.error;
+    if (err && typeof err === "object" && !Array.isArray(err)) {
+        const m = err.message;
+        if (typeof m === "string" && m.trim())
+            return m.trim();
+    }
+    if (typeof err === "string" && err.trim())
+        return err.trim();
+    if (ev.is_error === true && typeof ev.result === "string" && ev.result.trim())
+        return ev.result.trim();
+    if (typeof ev.message === "string" && ev.message.trim())
+        return ev.message.trim();
+    if (typeof ev.subtype === "string" && ev.subtype.trim() && ev.subtype !== "success")
+        return ev.subtype.trim();
+    return undefined;
 }
 //# sourceMappingURL=messages-stream.js.map

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -15,12 +15,14 @@ export type QmdReindexOptions = UtilityIo & {
         cwd: string;
     }) => unknown;
     sizeLimit?: (hqRoot: string) => unknown;
-    /** Test seams for the lock shared by every hq-cli embed entry point. */
+    /** Test seams for the lock shared by every hq-cli QMD writer. */
     embedLockDependencies?: EmbedLockDependencies;
     /** Test seams for the host load gate consulted while the embed lock is held. */
     loadGateDependencies?: LoadGateDependencies;
     /** Test seam for the hq-flags-gated warning on qmd native startup failures. */
     startupFailureWarningsEnabled?: () => boolean;
+    /** Test seam for the default-off shared lock around the full reindex pass. */
+    singleFlightEnabled?: () => boolean;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map