@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/status-consistency.mjs

@@ -0,0 +1,98 @@
+/**
+ * Reader-side revision consistency for the (state.json, status.json) pair
+ * (issue #91, spec D3 — 根治条件 5 read side).
+ *
+ * The View State Coordinator materializes both artifacts under one shared
+ * `materializedRevision` inside a single view lock. Disagreeing stamps
+ * therefore mean a coordinator crashed between its paired writes; readers
+ * must not combine the mismatched halves into one decision — skip the
+ * combination and request coordinator repair (a fresh coordinator's boot
+ * replay re-materializes the half-written pair from the journal).
+ *
+ * Legacy rows (written before revisions existed, or never touched by a
+ * command) may lack the field on either side; per the spec's legacy-migration
+ * clause the check is skipped for them — a missing stamp is never a desync.
+ */
+import { readState as readStateImpl, readStatus as readStatusImpl } from "./store.mjs";
+
+/**
+ * Whether the (state, status) pair is revision-desynced and must not be
+ * combined into one decision.
+ * @param {{ materializedRevision?: number|null }|null|undefined} state ViewState as read from state.json.
+ * @param {{ materializedRevision?: number|null }|null|undefined} status RunStatus as read from status.json.
+ * @returns {boolean}
+ */
+export function statusRevisionDesynced(state, status) {
+	if (state?.materializedRevision == null || status?.materializedRevision == null) return false;
+	return state.materializedRevision !== status.materializedRevision;
+}
+
+/**
+ * Re-read BOTH halves of the pair fresh and re-check the desync verdict.
+ *
+ * TOCTOU guard for long-lived readers (reconcile iterates a listRows snapshot;
+ * earlier rows' awaited commands let the on-disk pair advance past it): a
+ * suspicion raised against the snapshot must be confirmed against fresh reads
+ * before acting on it. Under the coordinator's view-lock pairing invariant
+ * both files move together, so a fresh consistent pair clears the suspicion;
+ * the residual window between the two fresh reads is sub-ms.
+ *
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string|null} runId
+ * @param {{ readState?: typeof readStateImpl, readStatus?: typeof readStatusImpl }} [readers] injection for tests.
+ * @returns {{ state: object|null, status: object|null, desynced: boolean }}
+ */
+export function rereadPair(root, viewId, runId, readers = {}) {
+	const readState = readers.readState ?? readStateImpl;
+	const readStatus = readers.readStatus ?? readStatusImpl;
+	const state = readState(root, viewId);
+	const status = readStatus(root, viewId, runId);
+	return { state, status, desynced: statusRevisionDesynced(state, status) };
+}
+
+/**
+ * Per-view episode throttle for desync reporting (issue #111 CR r1).
+ *
+ * A desync is a persistent CONDITION, not a one-shot event: reconcile runs on
+ * every dashboard poll (~700ms), and for unrepairable pairs (a torn transient
+ * beat has no journal record; or the coordinator is off) the condition never
+ * clears. Logging unthrottled would grow diagnostics.jsonl without bound.
+ * The throttle logs each distinct (stateRev:statusRev) pair once per viewer;
+ * a changed pair (progression, or a fresh crash at new revisions) logs again,
+ * and a repaired pair simply stops firing — no reset bookkeeping needed.
+ *
+ * Kick-retry tracking (issue #111 CR r2): a failed repair kick must not
+ * consume the recovery path — an idle dashboard would otherwise never run
+ * boot replay for a repairable pair. `markKickFailed`/`shouldRetryKick`
+ * track that independently of the diagnostic episode, so retries stay
+ * unbounded while the kick keeps failing while diagnostics stay once per
+ * episode. A successful kick clears the flag (the coordinator is up: boot
+ * replay already repaired a repairable pair; an unrepairable-torn pair
+ * gains nothing from re-kicking).
+ *
+ * @returns {{ shouldLog(viewId: string, stateRevision: number|null, statusRevision: number|null): boolean, markKickFailed(viewId: string): void, shouldRetryKick(viewId: string): boolean, clearKickFailed(viewId: string): void }}
+ */
+export function createDesyncEpisodeThrottle() {
+	/** @type {Map<string, string>} */
+	const lastLogged = new Map();
+	/** @type {Set<string>} */
+	const kickFailed = new Set();
+	return {
+		shouldLog(viewId, stateRevision, statusRevision) {
+			const pair = `${stateRevision ?? "null"}:${statusRevision ?? "null"}`;
+			if (lastLogged.get(viewId) === pair) return false;
+			lastLogged.set(viewId, pair);
+			return true;
+		},
+		markKickFailed(viewId) {
+			kickFailed.add(viewId);
+		},
+		shouldRetryKick(viewId) {
+			return kickFailed.has(viewId);
+		},
+		clearKickFailed(viewId) {
+			kickFailed.delete(viewId);
+		},
+	};
+}

package/packages/board/src/core/steering-prompts.mjs

@@ -0,0 +1,34 @@
+/** Prompt builders for steering-first Agent Board workflows. */
+
+/** @param {string} userText */
+export function buildPlanRequestPrompt(userText = "") {
+	const extra = String(userText || "").trim();
+	return [
+		"Create an implementation plan only. Do not modify files unless explicitly instructed by the user.",
+		"Return: scope, assumptions, proposed steps, validation plan, risks, and open questions.",
+		"This Agent Board plan mode is advisory; hard tool restrictions may not be enforced by the runtime yet.",
+		extra ? `User request/context: ${extra}` : "Use the current session context and repository state.",
+	].join("\n\n");
+}
+
+/** @param {string} planText */
+export function buildApprovePlanPrompt(planText = "") {
+	return [
+		"The user approved the plan below. Implement it now.",
+		"When finished, summarize changed files, commands/tests run, validation results, and residual risks for the Agent Board evidence panel.",
+		"Plan:",
+		String(planText || "(no plan text captured)"),
+	].join("\n\n");
+}
+
+/** @param {string} planText @param {string} feedback */
+export function buildPlanChangesPrompt(planText = "", feedback = "") {
+	return [
+		"Revise the implementation plan based on the user's feedback. Do not implement yet.",
+		"Return the revised plan and call out what changed.",
+		"Current plan:",
+		String(planText || "(no prior plan captured)"),
+		"User feedback:",
+		String(feedback || "(no feedback supplied)"),
+	].join("\n\n");
+}

package/packages/board/src/core/steering.mjs

@@ -0,0 +1,133 @@
+/** Durable steering / plan-approval state helpers. */
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import { truncate } from "./heuristics.mjs";
+import * as P from "./paths.mjs";
+
+const STATES = new Set(["none", "plan_requested", "awaiting_approval", "approved", "changes_requested", "executing_approved_plan"]);
+
+/** @param {string} viewId @param {number} [now] @returns {import("./types.mjs").SteeringState} */
+export function emptySteeringState(viewId, now = Date.now()) {
+	return {
+		version: 1,
+		viewId,
+		status: "none",
+		updatedAt: now,
+		planText: "",
+		planRunId: null,
+		approvedAt: null,
+		changeRequest: null,
+		executionRunId: null,
+		history: [],
+	};
+}
+
+/** @param {string} root @param {string} viewId */
+export function readSteering(root, viewId) {
+	return normalizeSteering(readJson(P.steeringPath(root, viewId), null), viewId);
+}
+
+/** @param {string} root @param {import("./types.mjs").SteeringState} state */
+export function writeSteering(root, state) {
+	const normalized = normalizeSteering(state, state.viewId);
+	normalized.updatedAt = Date.now();
+	atomicWriteJson(P.steeringPath(root, normalized.viewId), normalized);
+	return normalized;
+}
+
+/** @param {import("./types.mjs").SteeringState} state @returns {import("./types.mjs").SteeringSummary} */
+export function summarizeSteering(state) {
+	const s = normalizeSteering(state, state?.viewId ?? "");
+	return {
+		status: s.status,
+		awaitingApproval: s.status === "awaiting_approval",
+		planPreview: s.planText ? truncate(s.planText.replace(/\s+/g, " ").trim(), 180) : null,
+		updatedAt: s.updatedAt ?? null,
+		question: s.status === "awaiting_approval" ? "Approve this plan?" : null,
+	};
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null, note?: string }} [opts] */
+export function requestPlan(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	transition(state, "plan_requested", "request_plan", opts.runId ?? null, opts.note ?? null);
+	state.planRunId = opts.runId ?? state.planRunId ?? null;
+	return writeSteering(root, state);
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null, planText: string, note?: string }} opts */
+export function recordPlanReady(root, viewId, opts) {
+	const state = readSteering(root, viewId);
+	state.planText = String(opts.planText || "").trim();
+	state.planRunId = opts.runId ?? state.planRunId ?? null;
+	transition(state, "awaiting_approval", "plan_ready", opts.runId ?? null, opts.note ?? null);
+	return writeSteering(root, state);
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null, note?: string }} [opts] */
+export function approvePlan(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	if (state.status !== "awaiting_approval") return { ok: false, error: "No plan is awaiting approval", state };
+	state.approvedAt = Date.now();
+	state.executionRunId = opts.runId ?? null;
+	transition(state, "approved", "approve_plan", opts.runId ?? null, opts.note ?? null);
+	const saved = writeSteering(root, state);
+	return { ok: true, state: saved };
+}
+
+/** @param {string} root @param {string} viewId @param {string} feedback @param {{ runId?: string|null }} [opts] */
+export function requestPlanChanges(root, viewId, feedback, opts = {}) {
+	const clean = String(feedback || "").trim();
+	if (!clean) return { ok: false, error: "Empty change request", state: readSteering(root, viewId) };
+	const state = readSteering(root, viewId);
+	state.changeRequest = clean;
+	transition(state, "changes_requested", "request_plan_changes", opts.runId ?? null, clean);
+	const saved = writeSteering(root, state);
+	return { ok: true, state: saved };
+}
+
+/** @param {string} root @param {string} viewId @param {{ runId?: string|null }} [opts] */
+export function markExecutingApprovedPlan(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	state.executionRunId = opts.runId ?? state.executionRunId ?? null;
+	transition(state, "executing_approved_plan", "execute_approved_plan", opts.runId ?? null, null);
+	return writeSteering(root, state);
+}
+
+/** @param {string} root @param {string} viewId @param {{ note?: string }} [opts] */
+export function resetSteering(root, viewId, opts = {}) {
+	const state = readSteering(root, viewId);
+	transition(state, "none", "reset", null, opts.note ?? null);
+	state.planText = "";
+	state.planRunId = null;
+	state.approvedAt = null;
+	state.changeRequest = null;
+	state.executionRunId = null;
+	return writeSteering(root, state);
+}
+
+/** @param {any} state @param {string} viewId @returns {import("./types.mjs").SteeringState} */
+function normalizeSteering(state, viewId) {
+	const base = emptySteeringState(viewId || state?.viewId || "");
+	if (!state || typeof state !== "object") return base;
+	return {
+		...base,
+		...state,
+		viewId: typeof state.viewId === "string" ? state.viewId : base.viewId,
+		status: STATES.has(state.status) ? state.status : "none",
+		planText: typeof state.planText === "string" ? state.planText : "",
+		planRunId: typeof state.planRunId === "string" ? state.planRunId : null,
+		approvedAt: Number.isFinite(state.approvedAt) ? state.approvedAt : null,
+		changeRequest: typeof state.changeRequest === "string" ? state.changeRequest : null,
+		executionRunId: typeof state.executionRunId === "string" ? state.executionRunId : null,
+		history: Array.isArray(state.history) ? state.history : [],
+	};
+}
+
+/** @param {import("./types.mjs").SteeringState} state @param {import("./types.mjs").SteeringModeState} to @param {string} action @param {string|null} runId @param {string|null} note */
+function transition(state, to, action, runId, note) {
+	const now = Date.now();
+	const from = state.status;
+	state.status = to;
+	state.updatedAt = now;
+	state.history.push({ at: now, from, to, action, runId, note: note ? truncate(note, 240) : null });
+}

package/packages/board/src/core/stop-latch.mjs

@@ -0,0 +1,41 @@
+/**
+ * Minimal stop-intent latch for detached runners (issue #153).
+ *
+ * A runner installs signal handlers as early as module scope — before its
+ * config is even read — but the real stop path (kill worker, finalize the
+ * run) only exists once the worker is spawned and the close handlers are
+ * wired. A stop signal that lands in between must not die with Node's
+ * default action (that would leave the run without a terminal state); the
+ * latch records it and the runner replays it once the real stop path exists.
+ *
+ * Pure state: no signal wiring, no timers, no I/O.
+ */
+
+/**
+ * @returns {{
+ * 	note(signal: string): void,
+ * 	pending(): string | null,
+ * 	take(): string | null,
+ * }} A latch object. `note` is idempotent (the first signal wins, later ones
+ * collapse); `take` returns the recorded signal once, then null.
+ */
+export function createStopLatch() {
+	/** @type {string | null} */
+	let noted = null;
+	return {
+		/** Record a stop signal. @param {string} signal */
+		note(signal) {
+			if (noted == null) noted = signal;
+		},
+		/** The first recorded signal, or null. */
+		pending() {
+			return noted;
+		},
+		/** Read-and-clear: returns the recorded signal once, then null. */
+		take() {
+			const signal = noted;
+			noted = null;
+			return signal;
+		},
+	};
+}