sentinelayer-cli 0.6.2 → 0.8.1

package/src/session/scoring.js

@@ -0,0 +1,406 @@
+const SCORE_MODEL_VERSION = "1.0.0";
+const RESPONSE_TIME_HALF_LIFE_MS = 60_000;
+const FINDINGS_PER_DOLLAR_CAP = 10;
+
+const SCORE_WEIGHTS = Object.freeze({
+  findingsPerDollar: 0.2,
+  avgResponseTime: 0.15,
+  taskCompletionRate: 0.25,
+  conflictsCreated: 0.1,
+  stuckCount: 0.1,
+  reviewAccuracy: 0.2,
+});
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeNonNegativeNumber(value, fallbackValue = 0) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    return fallbackValue;
+  }
+  return normalized;
+}
+
+function normalizeRate(value, fallbackValue = 0) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized)) {
+    return fallbackValue;
+  }
+  return Math.max(0, Math.min(1, normalized));
+}
+
+function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    return fallbackIso;
+  }
+  const epoch = Date.parse(normalized);
+  if (!Number.isFinite(epoch)) {
+    return fallbackIso;
+  }
+  return new Date(epoch).toISOString();
+}
+
+function parseEpoch(value, fallbackIso = new Date().toISOString()) {
+  return Date.parse(normalizeIsoTimestamp(value, fallbackIso)) || 0;
+}
+
+function parseFindingCountFromMessage(message = "") {
+  const normalized = normalizeString(message);
+  if (!normalized) {
+    return 0;
+  }
+  if (/\bfinding\s*:\s*\[(P[0-3])\]/i.test(normalized)) {
+    return 1;
+  }
+  if (/\[(P[0-3])\]/i.test(normalized)) {
+    return 1;
+  }
+  return 0;
+}
+
+function parseHitlTruth(payload = {}) {
+  if (!payload || typeof payload !== "object") {
+    return null;
+  }
+  if (typeof payload.truth === "boolean") {
+    return payload.truth;
+  }
+  if (typeof payload.truthVerdict === "boolean") {
+    return payload.truthVerdict;
+  }
+  const normalized = normalizeString(
+    payload.truthVerdict || payload.truth || payload.verdict || payload.outcome || payload.action
+  ).toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  if (normalized === "confirmed" || normalized === "valid" || normalized === "true" || normalized === "accept") {
+    return true;
+  }
+  if (
+    normalized === "rejected" ||
+    normalized === "invalid" ||
+    normalized === "false" ||
+    normalized === "dismissed" ||
+    normalized === "overturned"
+  ) {
+    return false;
+  }
+  return null;
+}
+
+function isHitlEvent(eventName = "", payload = {}) {
+  const normalizedEvent = normalizeString(eventName).toLowerCase();
+  if (normalizedEvent.includes("hitl")) {
+    return true;
+  }
+  const channel = normalizeString(payload.channel).toLowerCase();
+  if (channel === "hitl") {
+    return true;
+  }
+  return Object.prototype.hasOwnProperty.call(payload, "truth") || Object.prototype.hasOwnProperty.call(payload, "truthVerdict");
+}
+
+function ensureMetricsRecord(metricsByAgent, agentId) {
+  const normalizedAgentId = normalizeString(agentId);
+  if (!normalizedAgentId) {
+    return null;
+  }
+  if (!metricsByAgent.has(normalizedAgentId)) {
+    metricsByAgent.set(normalizedAgentId, {
+      agentId: normalizedAgentId,
+      findings: 0,
+      costUsd: 0,
+      responseSamples: [],
+      avgResponseTimeMs: 0,
+      tasksAssigned: 0,
+      tasksCompleted: 0,
+      fileConflicts: 0,
+      stuckDetections: 0,
+      findingsConfirmed: 0,
+      findingsTotal: 0,
+      activeAssignments: 0,
+    });
+  }
+  return metricsByAgent.get(normalizedAgentId);
+}
+
+function finalizeMetrics(raw = {}) {
+  const tasksAssigned = normalizeNonNegativeNumber(raw.tasksAssigned, 0);
+  const tasksCompleted = normalizeNonNegativeNumber(raw.tasksCompleted, 0);
+  const responseSamples = Array.isArray(raw.responseSamples) ? raw.responseSamples : [];
+  const responseTotal = responseSamples.reduce((sum, value) => sum + normalizeNonNegativeNumber(value, 0), 0);
+  const avgResponseTimeMs = responseSamples.length > 0 ? Math.round(responseTotal / responseSamples.length) : 0;
+  return {
+    agentId: normalizeString(raw.agentId),
+    findings: normalizeNonNegativeNumber(raw.findings, 0),
+    costUsd: normalizeNonNegativeNumber(raw.costUsd, 0),
+    avgResponseTimeMs,
+    tasksAssigned,
+    tasksCompleted: Math.min(tasksCompleted, tasksAssigned || tasksCompleted),
+    fileConflicts: normalizeNonNegativeNumber(raw.fileConflicts, 0),
+    stuckDetections: normalizeNonNegativeNumber(raw.stuckDetections, 0),
+    findingsConfirmed: normalizeNonNegativeNumber(raw.findingsConfirmed, 0),
+    findingsTotal: normalizeNonNegativeNumber(raw.findingsTotal, 0),
+    activeAssignments: normalizeNonNegativeNumber(raw.activeAssignments, 0),
+  };
+}
+
+function toMetricsObject(metricsByAgent) {
+  const output = {};
+  for (const [agentId, metrics] of metricsByAgent.entries()) {
+    output[agentId] = finalizeMetrics(metrics);
+  }
+  return output;
+}
+
+function buildEmptyScore(agentId = "") {
+  return {
+    scoreModelVersion: SCORE_MODEL_VERSION,
+    agentId: normalizeString(agentId),
+    findingsPerDollar: 0,
+    avgResponseTimeMs: 0,
+    taskCompletionRate: 0,
+    conflictsCreated: 0,
+    stuckCount: 0,
+    reviewAccuracy: 0.5,
+    overallScore: 0,
+  };
+}
+
+function scoreFindingsPerDollar(value) {
+  const normalized = normalizeNonNegativeNumber(value, 0);
+  if (normalized <= 0) {
+    return 0;
+  }
+  return normalizeRate(normalized / FINDINGS_PER_DOLLAR_CAP, 0);
+}
+
+function scoreResponseTime(avgResponseTimeMs) {
+  const normalized = normalizeNonNegativeNumber(avgResponseTimeMs, 0);
+  if (normalized <= 0) {
+    return 1;
+  }
+  const score = 1 / (1 + normalized / RESPONSE_TIME_HALF_LIFE_MS);
+  return normalizeRate(score, 0);
+}
+
+function scorePenaltyCount(count) {
+  const normalized = normalizeNonNegativeNumber(count, 0);
+  return normalizeRate(1 / (1 + normalized), 0);
+}
+
+function computeOverallScore(components = {}) {
+  return normalizeRate(
+    components.findingsPerDollar * SCORE_WEIGHTS.findingsPerDollar +
+      components.avgResponseTime * SCORE_WEIGHTS.avgResponseTime +
+      components.taskCompletionRate * SCORE_WEIGHTS.taskCompletionRate +
+      components.conflictsCreated * SCORE_WEIGHTS.conflictsCreated +
+      components.stuckCount * SCORE_WEIGHTS.stuckCount +
+      components.reviewAccuracy * SCORE_WEIGHTS.reviewAccuracy,
+    0
+  );
+}
+
+function normalizeAgentMetrics(raw = {}) {
+  const tasksAssigned = normalizeNonNegativeNumber(raw.tasksAssigned, 0);
+  const tasksCompleted = normalizeNonNegativeNumber(raw.tasksCompleted, 0);
+  const findingsTotal = normalizeNonNegativeNumber(raw.findingsTotal, 0);
+  const findingsConfirmed = normalizeNonNegativeNumber(raw.findingsConfirmed, 0);
+  return {
+    findings: normalizeNonNegativeNumber(raw.findings, 0),
+    costUsd: normalizeNonNegativeNumber(raw.costUsd, 0),
+    avgResponseTimeMs: normalizeNonNegativeNumber(raw.avgResponseTimeMs, 0),
+    tasksAssigned,
+    tasksCompleted: Math.min(tasksCompleted, tasksAssigned || tasksCompleted),
+    fileConflicts: normalizeNonNegativeNumber(raw.fileConflicts, 0),
+    stuckDetections: normalizeNonNegativeNumber(raw.stuckDetections, 0),
+    findingsTotal,
+    findingsConfirmed: Math.min(findingsConfirmed, findingsTotal || findingsConfirmed),
+  };
+}
+
+function computeAgentScore(agentId, sessionAnalytics = {}) {
+  const normalizedAgentId = normalizeString(agentId);
+  if (!normalizedAgentId) {
+    return buildEmptyScore(agentId);
+  }
+  const metrics = normalizeAgentMetrics(sessionAnalytics);
+  const findingsPerDollar = metrics.findings / Math.max(metrics.costUsd, 0.01);
+  const taskCompletionRate =
+    metrics.tasksAssigned > 0 ? metrics.tasksCompleted / metrics.tasksAssigned : 0;
+  const reviewAccuracy =
+    metrics.findingsTotal > 0 ? metrics.findingsConfirmed / metrics.findingsTotal : 0.5;
+
+  const scoreComponents = {
+    findingsPerDollar: scoreFindingsPerDollar(findingsPerDollar),
+    avgResponseTime: scoreResponseTime(metrics.avgResponseTimeMs),
+    taskCompletionRate: normalizeRate(taskCompletionRate, 0),
+    conflictsCreated: scorePenaltyCount(metrics.fileConflicts),
+    stuckCount: scorePenaltyCount(metrics.stuckDetections),
+    reviewAccuracy: normalizeRate(reviewAccuracy, 0.5),
+  };
+  const overallScore = computeOverallScore(scoreComponents);
+
+  return {
+    scoreModelVersion: SCORE_MODEL_VERSION,
+    agentId: normalizedAgentId,
+    findingsPerDollar: Number(findingsPerDollar.toFixed(4)),
+    avgResponseTimeMs: Math.round(metrics.avgResponseTimeMs),
+    taskCompletionRate: Number(normalizeRate(taskCompletionRate, 0).toFixed(4)),
+    conflictsCreated: metrics.fileConflicts,
+    stuckCount: metrics.stuckDetections,
+    reviewAccuracy: Number(normalizeRate(reviewAccuracy, 0.5).toFixed(4)),
+    overallScore: Number(overallScore.toFixed(4)),
+  };
+}
+
+function buildAgentAnalyticsSnapshot({
+  events = [],
+  tasks = [],
+  activeAssignments = [],
+  nowIso = new Date().toISOString(),
+} = {}) {
+  const metricsByAgent = new Map();
+  const normalizedEvents = Array.isArray(events) ? [...events] : [];
+  normalizedEvents.sort((left, right) => parseEpoch(left?.ts, nowIso) - parseEpoch(right?.ts, nowIso));
+
+  let previousMessage = null;
+  for (const event of normalizedEvents) {
+    const eventName = normalizeString(event?.event);
+    const payload = event && typeof event.payload === "object" ? event.payload : {};
+    const eventAgentId =
+      normalizeString(event?.agent?.id || event?.agentId || payload.agentId || payload.reviewerId) || null;
+
+    if (eventName === "session_message") {
+      const messageAgent = eventAgentId;
+      if (messageAgent) {
+        const metrics = ensureMetricsRecord(metricsByAgent, messageAgent);
+        if (metrics) {
+          metrics.findings += parseFindingCountFromMessage(payload.message || "");
+          if (previousMessage && normalizeString(previousMessage.agentId) !== messageAgent) {
+            const deltaMs = parseEpoch(event?.ts, nowIso) - parseEpoch(previousMessage.ts, nowIso);
+            if (Number.isFinite(deltaMs) && deltaMs >= 0) {
+              metrics.responseSamples.push(deltaMs);
+            }
+          }
+        }
+      }
+      previousMessage = {
+        agentId: messageAgent,
+        ts: normalizeIsoTimestamp(event?.ts, nowIso),
+      };
+      continue;
+    }
+
+    if (eventName === "model_span" && eventAgentId) {
+      const metrics = ensureMetricsRecord(metricsByAgent, eventAgentId);
+      if (metrics) {
+        metrics.costUsd += normalizeNonNegativeNumber(payload.costUsd, 0);
+      }
+    }
+
+    if (eventName === "daemon_alert") {
+      const alert = normalizeString(payload.alert).toLowerCase();
+      if (alert === "file_conflict") {
+        const agentA = normalizeString(payload.agentA);
+        const agentB = normalizeString(payload.agentB);
+        const metricsA = ensureMetricsRecord(metricsByAgent, agentA);
+        const metricsB = ensureMetricsRecord(metricsByAgent, agentB);
+        if (metricsA) {
+          metricsA.fileConflicts += 1;
+        }
+        if (metricsB) {
+          metricsB.fileConflicts += 1;
+        }
+      }
+      if (alert === "stuck_detected") {
+        const stuckAgent = normalizeString(payload.agentId || payload.target);
+        const metrics = ensureMetricsRecord(metricsByAgent, stuckAgent);
+        if (metrics) {
+          metrics.stuckDetections += 1;
+        }
+      }
+    }
+
+    if (isHitlEvent(eventName, payload)) {
+      const reviewerId =
+        normalizeString(payload.reviewerId || payload.agentId || eventAgentId);
+      const truth = parseHitlTruth(payload);
+      const metrics = ensureMetricsRecord(metricsByAgent, reviewerId);
+      if (metrics && truth !== null) {
+        metrics.findingsTotal += 1;
+        if (truth) {
+          metrics.findingsConfirmed += 1;
+        }
+      }
+    }
+  }
+
+  const normalizedTasks = Array.isArray(tasks) ? tasks : [];
+  for (const task of normalizedTasks) {
+    const assignee = normalizeString(task?.toAgentId);
+    const metrics = ensureMetricsRecord(metricsByAgent, assignee);
+    if (!metrics) {
+      continue;
+    }
+    metrics.tasksAssigned += 1;
+    if (normalizeString(task?.status).toUpperCase() === "COMPLETED") {
+      metrics.tasksCompleted += 1;
+    }
+  }
+
+  const normalizedAssignments = Array.isArray(activeAssignments) ? activeAssignments : [];
+  for (const assignment of normalizedAssignments) {
+    const assignee = normalizeString(assignment?.assignedAgentIdentity);
+    const metrics = ensureMetricsRecord(metricsByAgent, assignee);
+    if (!metrics) {
+      continue;
+    }
+    metrics.activeAssignments += 1;
+  }
+
+  return toMetricsObject(metricsByAgent);
+}
+
+function compareRankedCandidates(left, right) {
+  if (left.score.overallScore !== right.score.overallScore) {
+    return right.score.overallScore - left.score.overallScore;
+  }
+  if (left.assignmentCount !== right.assignmentCount) {
+    return left.assignmentCount - right.assignmentCount;
+  }
+  if (left.statusWeight !== right.statusWeight) {
+    return left.statusWeight - right.statusWeight;
+  }
+  if (left.activityEpoch !== right.activityEpoch) {
+    return left.activityEpoch - right.activityEpoch;
+  }
+  return left.agentId.localeCompare(right.agentId);
+}
+
+function rankAgentsByScore(candidates = [], analyticsByAgent = {}) {
+  const normalizedCandidates = Array.isArray(candidates) ? candidates : [];
+  const ranked = normalizedCandidates.map((candidate) => {
+    const agentId = normalizeString(candidate?.agentId);
+    const agentAnalytics =
+      analyticsByAgent && typeof analyticsByAgent === "object" ? analyticsByAgent[agentId] || {} : {};
+    const score = computeAgentScore(agentId, agentAnalytics);
+    return {
+      ...candidate,
+      score,
+    };
+  });
+  ranked.sort(compareRankedCandidates);
+  return ranked;
+}
+
+export {
+  SCORE_MODEL_VERSION,
+  buildAgentAnalyticsSnapshot,
+  computeAgentScore,
+  rankAgentsByScore,
+};

package/src/session/setup-guides.js

@@ -0,0 +1,304 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { buildAgentsSessionGuideContent } from "../legacy-cli.js";
+import { getSession } from "./store.js";
+
+const SECTION_START_MARKER = "<!-- SENTINELAYER_SESSION_COORDINATION:START -->";
+const SECTION_END_MARKER = "<!-- SENTINELAYER_SESSION_COORDINATION:END -->";
+const SECTION_HEADING = "## Multi-Agent Session Coordination (SentinelLayer)";
+const SESSION_GUIDE_RELATIVE_PATH = path.join(".sentinelayer", "AGENTS_SESSION_GUIDE.md");
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeLineEndings(value = "") {
+  return String(value || "").replace(/\r\n/g, "\n");
+}
+
+function normalizeHeadingText(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function buildSessionCoordinationSection() {
+  return `${SECTION_START_MARKER}
+${SECTION_HEADING}
+
+### Before You Start
+- Check for active sessions: \`sl session list\`
+- Join if one exists: \`sl session join <id> --name <your-name>\`
+- Read recent context: \`sl session read <id> --tail 20\`
+
+### While Working
+- Emit status every 5 min: \`sl session say <id> "status: <what you're doing>"\`
+- Lock files before editing: \`sl session say <id> "lock: <file> - <intent>"\`
+- Unlock when done: \`sl session say <id> "unlock: <file> - done"\`
+- Post findings: \`sl session say <id> "finding: [P2] <title> in <file>:<line>"\`
+
+### On Problems
+- Unexpected file change? Ask: \`sl session say <id> "help: unexpected change in <file>"\`
+- Need another agent's work? Request: \`sl session say <id> "handoff: @<agent> <description>"\`
+- Found issues for others? Assign: \`sl session say <id> "assign: @<agent> <task>"\`
+
+### What Not To Do
+- Do not break your autonomous loop on unexpected file changes; ask in session first.
+- Do not edit files locked by another agent; wait or coordinate.
+- Do not push without checking session activity on files you touched.
+- Do not ignore daemon alerts; post a status update if flagged as stuck.
+
+### Budget Awareness
+- Share usage: \`sl session say <id> "budget: 40K/50K tokens used"\`
+- Signal low budget and handoff: \`sl session say <id> "budget-low: 90% used, handing off <task>"\`
+${SECTION_END_MARKER}
+`;
+}
+
+function splitLines(value) {
+  return normalizeLineEndings(value).split("\n");
+}
+
+function findLegacySectionRange(lines = []) {
+  const targetHeading = normalizeHeadingText(SECTION_HEADING.replace(/^##\s*/, ""));
+  const startIndex = lines.findIndex(
+    (line) => normalizeHeadingText(line.replace(/^#+\s*/, "")) === targetHeading
+  );
+  if (startIndex < 0) {
+    return null;
+  }
+  let endIndexExclusive = lines.length;
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index])) {
+      endIndexExclusive = index;
+      break;
+    }
+  }
+  return {
+    startIndex,
+    endIndexExclusive,
+  };
+}
+
+function upsertCoordinationSection(existingText = "", sectionText = buildSessionCoordinationSection()) {
+  const normalizedExisting = normalizeLineEndings(existingText);
+  const normalizedSection = normalizeLineEndings(sectionText).trimEnd();
+  if (!normalizeString(normalizedExisting)) {
+    return {
+      content: `${normalizedSection}\n`,
+      changed: true,
+    };
+  }
+
+  const markerPattern = new RegExp(
+    `${SECTION_START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${SECTION_END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+    "m"
+  );
+  if (markerPattern.test(normalizedExisting)) {
+    const replaced = normalizedExisting.replace(markerPattern, normalizedSection);
+    const finalText = `${replaced.trimEnd()}\n`;
+    return {
+      content: finalText,
+      changed: finalText !== `${normalizedExisting.trimEnd()}\n`,
+    };
+  }
+
+  const lines = splitLines(normalizedExisting);
+  const legacyRange = findLegacySectionRange(lines);
+  if (legacyRange) {
+    const before = lines.slice(0, legacyRange.startIndex).join("\n").trimEnd();
+    const after = lines.slice(legacyRange.endIndexExclusive).join("\n").trimStart();
+    const stitched = [before, normalizedSection, after].filter(Boolean).join("\n\n");
+    const finalText = `${stitched.trimEnd()}\n`;
+    return {
+      content: finalText,
+      changed: finalText !== `${normalizedExisting.trimEnd()}\n`,
+    };
+  }
+
+  const appended = `${normalizedExisting.trimEnd()}\n\n${normalizedSection}\n`;
+  return {
+    content: appended,
+    changed: appended !== `${normalizedExisting.trimEnd()}\n`,
+  };
+}
+
+async function readOptionalFile(filePath) {
+  try {
+    return await fsp.readFile(filePath, "utf-8");
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function writeTextFile(filePath, content) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, normalizeLineEndings(content), "utf-8");
+}
+
+function buildDefaultGuideDoc(fileName, sectionText) {
+  const title = fileName === "CLAUDE.md" ? "CLAUDE" : "AGENTS";
+  return `# ${title}
+
+${sectionText.trimEnd()}
+`;
+}
+
+async function upsertInstructionGuide(filePath, sectionText, { createIfMissing = true } = {}) {
+  const existing = await readOptionalFile(filePath);
+  if (existing === null) {
+    if (!createIfMissing) {
+      return {
+        path: filePath,
+        existed: false,
+        changed: false,
+        content: "",
+      };
+    }
+    const createdContent = buildDefaultGuideDoc(path.basename(filePath), sectionText);
+    await writeTextFile(filePath, createdContent);
+    return {
+      path: filePath,
+      existed: false,
+      changed: true,
+      content: createdContent,
+    };
+  }
+  const upserted = upsertCoordinationSection(existing, sectionText);
+  if (upserted.changed) {
+    await writeTextFile(filePath, upserted.content);
+  }
+  return {
+    path: filePath,
+    existed: true,
+    changed: upserted.changed,
+    content: upserted.content,
+  };
+}
+
+function countCoordinationSections(content = "") {
+  const text = normalizeLineEndings(content);
+  const markerCount = (text.match(new RegExp(SECTION_START_MARKER, "g")) || []).length;
+  if (markerCount > 0) {
+    return markerCount;
+  }
+  return (text.match(new RegExp(SECTION_HEADING.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g")) || [])
+    .length;
+}
+
+async function resolveSessionContext(sessionId, { targetPath = process.cwd() } = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const normalizedTargetPath = path.resolve(String(targetPath || "."));
+  const session = await getSession(normalizedSessionId, {
+    targetPath: normalizedTargetPath,
+  });
+  if (!session) {
+    throw new Error(`Session '${normalizedSessionId}' was not found.`);
+  }
+  return {
+    sessionId: normalizedSessionId,
+    targetPath: normalizedTargetPath,
+  };
+}
+
+function summarizeInstructionGuide(result = {}) {
+  return {
+    path: result.path,
+    existed: result.existed,
+    changed: result.changed,
+    sectionCount: countCoordinationSections(result.content),
+  };
+}
+
+function resolveInstructionGuidePaths(targetPath) {
+  return {
+    agentsPath: path.join(targetPath, "AGENTS.md"),
+    claudePath: path.join(targetPath, "CLAUDE.md"),
+    guidePath: path.join(targetPath, SESSION_GUIDE_RELATIVE_PATH),
+  };
+}
+
+export async function setupSessionGuides(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+  } = {}
+) {
+  const context = await resolveSessionContext(sessionId, {
+    targetPath,
+  });
+
+  const sectionText = buildSessionCoordinationSection();
+  const { agentsPath, claudePath, guidePath } = resolveInstructionGuidePaths(context.targetPath);
+
+  const [agentsResult, claudeResult] = await Promise.all([
+    upsertInstructionGuide(agentsPath, sectionText),
+    upsertInstructionGuide(claudePath, sectionText),
+  ]);
+
+  const guideContent = `${normalizeLineEndings(buildAgentsSessionGuideContent()).trimEnd()}\n`;
+  const existingGuide = await readOptionalFile(guidePath);
+  const normalizedExistingGuide = existingGuide === null ? null : `${normalizeLineEndings(existingGuide).trimEnd()}\n`;
+  const guideChanged = normalizedExistingGuide !== guideContent;
+  if (guideChanged) {
+    await writeTextFile(guidePath, guideContent);
+  }
+
+  return {
+    sessionId: context.sessionId,
+    targetPath: context.targetPath,
+    sectionHeading: SECTION_HEADING,
+    agents: summarizeInstructionGuide(agentsResult),
+    claude: summarizeInstructionGuide(claudeResult),
+    sessionGuide: {
+      path: guidePath,
+      existed: existingGuide !== null,
+      changed: guideChanged,
+    },
+  };
+}
+
+export async function injectSessionGuides(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+  } = {}
+) {
+  const context = await resolveSessionContext(sessionId, {
+    targetPath,
+  });
+  const sectionText = buildSessionCoordinationSection();
+  const { agentsPath, claudePath } = resolveInstructionGuidePaths(context.targetPath);
+  const [agentsResult, claudeResult] = await Promise.all([
+    upsertInstructionGuide(agentsPath, sectionText, {
+      createIfMissing: false,
+    }),
+    upsertInstructionGuide(claudePath, sectionText, {
+      createIfMissing: false,
+    }),
+  ]);
+
+  return {
+    sessionId: context.sessionId,
+    targetPath: context.targetPath,
+    sectionHeading: SECTION_HEADING,
+    agents: summarizeInstructionGuide(agentsResult),
+    claude: summarizeInstructionGuide(claudeResult),
+  };
+}
+
+export {
+  SECTION_END_MARKER,
+  SECTION_HEADING,
+  SECTION_START_MARKER,
+  SESSION_GUIDE_RELATIVE_PATH,
+  buildSessionCoordinationSection,
+  countCoordinationSections,
+  upsertCoordinationSection,
+};