sentinelayer-cli 0.23.0 → 0.25.0

package/src/guide/enrich.js

@@ -0,0 +1,173 @@
+/**
+ * Optional LLM enrichment for the deterministic decomposition.
+ *
+ * The heuristic in generator.js produces one ticket per phase. This layer asks
+ * a model to split each phase into concrete, independently-mergeable per-PR
+ * tickets with sharper acceptance criteria. It is:
+ *  - opt-in (the caller passes a client),
+ *  - capped (bounded phases × tickets, so cost is bounded),
+ *  - fail-safe (any phase that errors or returns junk keeps its heuristic
+ *    ticket — enrichment never throws and never drops work).
+ */
+
+export const DEFAULT_ENRICH_LIMITS = Object.freeze({
+  maxPhases: 12,
+  maxTicketsPerPhase: 4,
+});
+
+function clampInt(value, fallback, min, max) {
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, n));
+}
+
+export function buildEnrichPrompt(phase, maxTickets) {
+  const fields = phase?.fields || {};
+  const lines = [
+    `Phase: ${String(phase?.title || "").trim()}`,
+    fields.objective ? `Objective: ${fields.objective}` : "",
+    fields.files ? `Files: ${fields.files}` : "",
+    fields.tests ? `Tests: ${fields.tests}` : "",
+    Array.isArray(phase?.tasks) && phase.tasks.length
+      ? `Tasks:\n${phase.tasks.map((task) => `- ${task}`).join("\n")}`
+      : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return `You are splitting ONE software build phase into concrete, independently-mergeable pull requests.
+Return ONLY a JSON array (no prose, no markdown fences) of 1 to ${maxTickets} objects. Each object:
+{"title": "imperative summary, <= 80 chars", "summary": "one sentence", "acceptance_criteria": ["short testable bullet", "..."]}
+Rules: keep each PR small and shippable on its own; order them by dependency; 2-4 acceptance criteria each; no commentary.
+
+${lines}`;
+}
+
+/** Pull a JSON array out of a model response, tolerating code fences / prose. */
+export function extractJsonArray(text) {
+  const raw = String(text || "").trim();
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const body = (fenced ? fenced[1] : raw).trim();
+  const start = body.indexOf("[");
+  const end = body.lastIndexOf("]");
+  if (start === -1 || end === -1 || end <= start) return null;
+  try {
+    const parsed = JSON.parse(body.slice(start, end + 1));
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeSubTickets(parsed, maxTickets) {
+  if (!Array.isArray(parsed)) return null;
+  const out = [];
+  for (const item of parsed.slice(0, maxTickets)) {
+    const title = String(item?.title || "").trim();
+    if (!title) continue;
+    const summary = String(item?.summary || "").trim();
+    const acceptanceCriteria = Array.isArray(item?.acceptance_criteria)
+      ? item.acceptance_criteria
+          .map((value) => String(value || "").trim())
+          .filter(Boolean)
+          .slice(0, 6)
+      : [];
+    out.push({ title: title.slice(0, 120), summary, acceptanceCriteria });
+  }
+  return out.length ? out : null;
+}
+
+/** Enrich a single phase → array of {title, summary, acceptanceCriteria} or null. */
+export async function enrichPhase({ phase, client, provider, model, apiKey, env, maxTicketsPerPhase }) {
+  if (!client || typeof client.invoke !== "function") return null;
+  const cap = clampInt(maxTicketsPerPhase, DEFAULT_ENRICH_LIMITS.maxTicketsPerPhase, 1, 10);
+  try {
+    const result = await client.invoke({
+      provider,
+      model,
+      prompt: buildEnrichPrompt(phase, cap),
+      apiKey,
+      env,
+      stream: false,
+    });
+    return normalizeSubTickets(extractJsonArray(result?.text), cap);
+  } catch {
+    return null;
+  }
+}
+
+function subTicketDescription({ summary, acceptanceCriteria, dependencyLine }) {
+  const acBlock = acceptanceCriteria.length
+    ? acceptanceCriteria.map((item, index) => `${index + 1}. ${item}`).join("\n")
+    : "1. Phase outcomes are verified by deterministic checks.";
+  return [
+    `Dependencies: ${dependencyLine}`,
+    "",
+    summary ? `${summary}\n` : "",
+    "Acceptance criteria:",
+    acBlock,
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Produce an enriched ticket list from a generated guide. Each enriched phase
+ * expands into per-PR sub-tickets; phases beyond the cap, or that fail, keep
+ * their original heuristic ticket. Returns { tickets, enrichedPhases }.
+ */
+export async function enrichGuideTickets({ guide, client, provider, model, apiKey, env, limits } = {}) {
+  const phases = Array.isArray(guide?.phases) ? guide.phases : [];
+  const baseTickets = Array.isArray(guide?.tickets) ? guide.tickets : [];
+  const maxPhases = clampInt(limits?.maxPhases, DEFAULT_ENRICH_LIMITS.maxPhases, 1, 50);
+  const maxTicketsPerPhase = clampInt(
+    limits?.maxTicketsPerPhase,
+    DEFAULT_ENRICH_LIMITS.maxTicketsPerPhase,
+    1,
+    10,
+  );
+
+  const tickets = [];
+  let enrichedPhases = 0;
+
+  for (let index = 0; index < phases.length; index += 1) {
+    const phase = phases[index];
+    const baseTicket = baseTickets[index];
+    const subTickets =
+      index < maxPhases
+        ? await enrichPhase({ phase, client, provider, model, apiKey, env, maxTicketsPerPhase })
+        : null;
+
+    if (!subTickets) {
+      if (baseTicket) tickets.push(baseTicket);
+      continue;
+    }
+
+    enrichedPhases += 1;
+    const issueNumber = index + 1;
+    const phaseDeps = baseTicket?.dependencies || phase?.dependencies || [];
+    const baseLabels = baseTicket?.labels || ["sentinelayer", "build-guide", `phase-${issueNumber}`];
+
+    subTickets.forEach((sub, subIndex) => {
+      const dependencies =
+        subIndex === 0 ? phaseDeps : [tickets[tickets.length - 1].title];
+      const dependencyLine = dependencies.length > 0 ? dependencies.join(", ") : "none (entry phase)";
+      tickets.push({
+        id: `phase-${issueNumber}.${subIndex + 1}`,
+        phase_id: baseTicket?.phase_id || phase?.phaseId || "",
+        title: sub.title,
+        estimate_hours: baseTicket?.estimate_hours || { min: 4, max: 8 },
+        dependencies,
+        dependency_ids: subIndex === 0 ? baseTicket?.dependency_ids || [] : [],
+        labels: [...baseLabels, "pr"],
+        description: subTicketDescription({
+          summary: sub.summary,
+          acceptanceCriteria: sub.acceptanceCriteria,
+          dependencyLine,
+        }),
+      });
+    });
+  }
+
+  return { tickets, enrichedPhases };
+}

package/src/guide/generator.js

@@ -41,6 +41,29 @@ function parseNumberedLines(block) {
     .filter(Boolean);
 }
 
+// Labeled bullets the builder emits per phase (e.g. "- Objective: ...").
+// We capture these as structured fields so ticket bodies carry real content
+// instead of dropping every non-numbered line.
+const PHASE_FIELD_LABELS = new Map([
+  ["objective", "objective"],
+  ["dependencies", "dependencies"],
+  ["files", "files"],
+  ["commands", "commands"],
+  ["tests", "tests"],
+  ["rollback", "rollback"],
+  ["evidence", "evidence"],
+]);
+
+// "Phase 0 (P0) — Repo Bootstrap" -> "P0"; "Phase 2 ..." -> "P2".
+function parsePhaseHeadingId(title) {
+  const paren = String(title || "").match(/\(\s*([A-Za-z]+\d+)\s*\)/);
+  if (paren) {
+    return paren[1].toUpperCase();
+  }
+  const phaseNum = String(title || "").match(/^Phase\s+(\d+)\b/i);
+  return phaseNum ? `P${phaseNum[1]}` : "";
+}
+
 function parsePhasePlan(specMarkdown) {
   const phaseBlock = sectionBody(specMarkdown, "Phase Plan");
   if (!phaseBlock) {
@@ -58,16 +81,39 @@ function parsePhasePlan(specMarkdown) {
       if (current) {
         phases.push(current);
       }
+      const title = headingMatch[1].trim();
       current = {
-        title: headingMatch[1].trim(),
+        title,
+        phaseId: parsePhaseHeadingId(title),
         tasks: [],
+        fields: {},
       };
       continue;
     }
 
+    if (!current) {
+      continue;
+    }
+
     const taskMatch = line.match(/^\d+\.\s+(.+)$/);
-    if (taskMatch && current) {
+    if (taskMatch) {
       current.tasks.push(taskMatch[1].trim());
+      continue;
+    }
+
+    const bulletMatch = line.match(/^[-*]\s+(.+)$/);
+    if (bulletMatch) {
+      const body = bulletMatch[1].trim();
+      const labelMatch = body.match(/^([A-Za-z][A-Za-z ]*?):\s*(.*)$/);
+      if (labelMatch) {
+        const key = labelMatch[1].trim().toLowerCase();
+        if (PHASE_FIELD_LABELS.has(key)) {
+          current.fields[PHASE_FIELD_LABELS.get(key)] = labelMatch[2].trim();
+          continue;
+        }
+      }
+      // An unlabeled bullet is real work -> treat it as a task.
+      current.tasks.push(body);
     }
   }
 
@@ -78,6 +124,46 @@ function parsePhasePlan(specMarkdown) {
   return phases;
 }
 
+// Expand a dependency token into phase ids: "P0-P4" -> [P0..P4], "P0" -> [P0].
+function expandPhaseRange(token) {
+  const raw = String(token || "").trim();
+  if (!raw) {
+    return [];
+  }
+  const range = raw.match(/^([A-Za-z]+)(\d+)\s*[-–—]\s*([A-Za-z]+)?(\d+)$/);
+  if (range) {
+    const prefix = range[1].toUpperCase();
+    const start = Number(range[2]);
+    const end = Number(range[4]);
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start && end - start <= 50) {
+      const out = [];
+      for (let value = start; value <= end; value += 1) {
+        out.push(`${prefix}${value}`);
+      }
+      return out;
+    }
+  }
+  const single = raw.match(/^([A-Za-z]+\d+)$/);
+  return single ? [single[1].toUpperCase()] : [];
+}
+
+// Parse a declared "Dependencies" field into a list of phase ids.
+function parseDeclaredDependencies(value) {
+  const raw = String(value || "").trim();
+  if (!raw || /^none\b/i.test(raw)) {
+    return [];
+  }
+  const ids = [];
+  for (const part of raw.split(/[,;]/)) {
+    for (const id of expandPhaseRange(part)) {
+      if (!ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+  }
+  return ids;
+}
+
 function parseProjectName(specMarkdown) {
   const match = String(specMarkdown || "").match(/^#\s*SPEC\s*-\s*(.+)$/im);
   return match ? match[1].trim() : "Project";
@@ -113,19 +199,58 @@ function estimateEffortHours({ phaseTitle, taskCount, riskSurfaceCount }) {
   };
 }
 
-function normalizeAcceptanceCriteria(specMarkdown, phaseTasks) {
+// Real, phase-specific acceptance criteria derived from the captured fields
+// (Tests/Evidence/Objective) and any tasks, instead of an empty placeholder.
+function derivePhaseAcceptance(specMarkdown, phase) {
   const globalCriteria = parseNumberedLines(sectionBody(specMarkdown, "Acceptance Criteria"));
   if (globalCriteria.length > 0) {
-    return globalCriteria.slice(0, 3);
+    return globalCriteria.slice(0, 5);
+  }
+  const fields = phase.fields || {};
+  const out = [];
+  if (fields.tests) {
+    out.push(`Tests pass: ${fields.tests}`);
+  }
+  if (fields.evidence) {
+    out.push(`Evidence captured: ${fields.evidence}`);
+  }
+  if (fields.objective) {
+    out.push(`Objective met: ${fields.objective}`);
   }
-  return phaseTasks.slice(0, 3).map((task) => `Validated completion: ${task}`);
+  for (const task of (phase.tasks || []).slice(0, 3)) {
+    out.push(`Completed: ${task}`);
+  }
+  if (out.length === 0) {
+    out.push("Phase outcomes are verified by deterministic checks.");
+  }
+  return out.slice(0, 5);
+}
+
+// Structured detail lines (objective/files/tests/...) for the ticket body.
+function renderPhaseDetailLines(phase) {
+  const fields = phase.fields || {};
+  const order = ["objective", "files", "commands", "tests", "rollback", "evidence"];
+  const labels = {
+    objective: "Objective",
+    files: "Files",
+    commands: "Commands",
+    tests: "Tests",
+    rollback: "Rollback",
+    evidence: "Evidence",
+  };
+  return order
+    .filter((key) => String(fields[key] || "").trim().length > 0)
+    .map((key) => `${labels[key]}: ${fields[key]}`);
 }
 
 function renderPhaseMarkdown(phase) {
+  const detailLines = renderPhaseDetailLines(phase);
+  const detailBlock =
+    detailLines.length > 0 ? `\n${detailLines.map((line) => `- ${line}`).join("\n")}` : "";
   const taskLines =
     phase.tasks.length > 0
       ? phase.tasks.map((task, index) => `${index + 1}. ${task}`).join("\n")
-      : "1. Define implementation tasks for this phase.";
+      : "1. Deliver the phase objective above with deterministic checks.";
   const acceptanceLines =
     phase.acceptanceCriteria.length > 0
       ? phase.acceptanceCriteria.map((item, index) => `${index + 1}. ${item}`).join("\n")
@@ -135,7 +260,7 @@ function renderPhaseMarkdown(phase) {
 
   return `### ${phase.title}
 - Estimated effort: ${phase.effort.label}
-- Dependencies: ${dependencyLine}
+- Dependencies: ${dependencyLine}${detailBlock}
 
 #### Implementation Tasks
 ${taskLines}
@@ -147,29 +272,38 @@ ${acceptanceLines}
 
 function buildTicket(phase, index) {
   const issueNumber = index + 1;
+  const phaseId = String(phase.phaseId || "").trim();
   const labels = ["sentinelayer", "build-guide", `phase-${issueNumber}`];
+  if (phaseId) {
+    labels.push(phaseId.toLowerCase());
+  }
   const dependencyLine =
     phase.dependencies.length > 0 ? phase.dependencies.join(", ") : "none (entry phase)";
   const acceptanceBlock = phase.acceptanceCriteria
     .map((item, criterionIndex) => `${criterionIndex + 1}. ${item}`)
     .join("\n");
   const taskBlock = phase.tasks.map((task, taskIndex) => `${taskIndex + 1}. ${task}`).join("\n");
+  const detailLines = renderPhaseDetailLines(phase);
+  const detailBlock = detailLines.length > 0 ? ["Details:", ...detailLines, ""] : [];
 
   return {
     id: `phase-${issueNumber}`,
+    phase_id: phaseId,
     title: phase.title,
     estimate_hours: {
       min: phase.effort.minHours,
       max: phase.effort.maxHours,
     },
     dependencies: phase.dependencies,
+    dependency_ids: phase.dependencyIds || [],
     labels,
     description: [
       `Dependencies: ${dependencyLine}`,
       `Estimated effort: ${phase.effort.label}`,
       "",
+      ...detailBlock,
       "Implementation tasks:",
-      taskBlock || "1. Define implementation tasks for this phase.",
+      taskBlock || "1. Deliver the phase objective above with deterministic checks.",
       "",
       "Acceptance criteria:",
       acceptanceBlock || "1. Phase outcomes are verified by deterministic checks.",
@@ -210,19 +344,42 @@ export function generateBuildGuide({
   const goal = parseGoal(source);
   const riskSurfaceCount = parseRiskSurfaceCount(source);
 
+  // Map declared phase ids (P0, P1, ...) to titles so a "Dependencies: P0-P1"
+  // line resolves to a real prerequisite graph instead of naive sequencing.
+  const idToTitle = new Map(
+    phases.filter((phase) => phase.phaseId).map((phase) => [phase.phaseId, phase.title])
+  );
+
   const resolvedPhases = phases.map((phase, index) => {
-    const dependencies = index > 0 ? [phases[index - 1].title] : [];
+    const declaredIds = parseDeclaredDependencies(phase.fields?.dependencies);
+    const knownIds = declaredIds.filter(
+      (id) => idToTitle.has(id) && idToTitle.get(id) !== phase.title
+    );
+    let dependencies;
+    if (knownIds.length > 0) {
+      // Honor the spec's declared dependency graph.
+      dependencies = knownIds.map((id) => idToTitle.get(id));
+    } else if (declaredIds.length === 0 && index > 0) {
+      // Nothing declared -> fall back to the previous phase only.
+      dependencies = [phases[index - 1].title];
+    } else {
+      // Declared "none", or deps that don't resolve -> entry phase.
+      dependencies = [];
+    }
     const effort = estimateEffortHours({
       phaseTitle: phase.title,
       taskCount: phase.tasks.length,
       riskSurfaceCount,
     });
-    const acceptanceCriteria = normalizeAcceptanceCriteria(source, phase.tasks);
+    const acceptanceCriteria = derivePhaseAcceptance(source, phase);
 
     return {
       title: phase.title,
+      phaseId: phase.phaseId,
       tasks: phase.tasks,
+      fields: phase.fields,
       dependencies,
+      dependencyIds: knownIds,
       effort,
       acceptanceCriteria,
     };

package/src/legacy-cli.js

@@ -2133,6 +2133,13 @@ Project: ${projectName}
 - [ ] Re-run gate and confirm clean status.
 - [ ] Merge only after quality gates are green.
 
+## Ticket Trail Contract (Per PR — lean, only if the project has a board/Jira)
+- [ ] One ticket = one PR; the PR body carries the ticket id.
+- [ ] On PR open: move the ticket to In-review + comment the PR link.
+- [ ] On merge + green: move the ticket to Done + comment "merged, gate green".
+- [ ] On gate fail: move the ticket to Blocked + the finding.
+- [ ] One update per transition — not every step (same discipline as senti).
+
 ## Command Roadmap (Local Terminal)
 - [ ] \`sentinel /omargate deep --path <repo>\`: local deep scan pipeline
 - [ ] \`sentinel /audit --path <repo>\`: security + quality audit summary
@@ -2219,6 +2226,13 @@ Execution mode:
 - Keep commits scoped and deterministic.
 - Stop only for blocking secrets/permission gaps.
 
+Ticket trail (lean, only if the project has a board/Jira — do this on every PR, not every step):
+- One ticket = one PR; put the ticket id in the PR body.
+- On PR open -> move the ticket to In-review and comment the PR link.
+- On merge + green -> move the ticket to Done and comment "merged, gate green".
+- On gate fail -> move the ticket to Blocked with the finding.
+- Post one short senti update per transition (same discipline as the ticket).
+
 Coding agent profile:
 - Selected agent: ${codingAgentProfile.name} (${codingAgentProfile.id})
 - Prompt target: ${codingAgentProfile.promptTarget}
@@ -2280,6 +2294,9 @@ ${renderCoordinationNumberedList()}
 - Finding: \`sl session say <id> "finding: [P2] missing rate limit on POST /api/auth/login"\`
 - Help: \`sl session say <id> "help: unexpected change in package.json - who modified it?"\`
 - Done: \`sl session say <id> "done: PR merged, auth hardening complete"\`
+
+## Reserved Seat Onboarding
+- If \`sl session join\` returns \`onboardingGuide.markdownPath\`, read that file before posting; it contains your reserved-seat SOUL instructions, role, and first actions.
 `;
 }
 

package/src/session/first-message.js

@@ -0,0 +1,99 @@
+import { createAgentEvent } from "../events/schema.js";
+import { appendToStream } from "./stream.js";
+
+export const FIRST_MESSAGE_AGENT = Object.freeze({
+  id: "senti",
+  model: "senti",
+  persona: "Senti",
+  shortName: "Senti",
+  color: "magenta",
+  avatar: "S",
+});
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+/**
+ * The deterministic "first Senti message" pinned to every new session —
+ * the approved Carter draft combining the GPT/Codex lanes and the Claude
+ * lane. Model-aware (each agent uses the path that fits its runtime),
+ * command-accurate, low-power. `<AGENT_ID>` stays a placeholder each agent
+ * substitutes; the session id is filled in.
+ */
+export function buildFirstSentiMessage({ sessionId } = {}) {
+  const sid = normalizeString(sessionId) || "<SID>";
+  return [
+    `👋 Welcome to this Senti coding room (session ${sid}). The transcript IS the deliverable evidence. Don't go dark, don't make top-level noise. Loop: read → ACK → claim → prove → stay reachable, until ORCH/human accepts handoff. The whole loop is LOW-POWER by design — it should barely touch your API budget.`,
+    "",
+    "IDENTITY — your name = lane + model (api-01-gpt-5.5, ui-01-gpt-5.5, verify-01-opus-4.8).",
+    "",
+    "MANDATORY FIRST COMMANDS, in order:",
+    `1) sl --help && sl session --help   (trust local help over memory)`,
+    `2) sl session join ${sid} --agent <AGENT_ID> --model <MODEL> --role <role>`,
+    `3) sl ai identity provision --execute ; sl ai identity list`,
+    `4) sl session pins ${sid} --json`,
+    `5) sl session read ${sid} --remote --agent <AGENT_ID> --tail 60   (records your view receipt)`,
+    `6) sl session react ${sid} ack --target-sequence <THIS_SEQ> --agent <AGENT_ID>`,
+    `7) sl session reply ${sid} <THIS_SEQ> "ACK <AGENT_ID> role=<role> model=<model> locks=none first_action=<one concrete action>" --agent <AGENT_ID>`,
+    "",
+    "STAY REACHABLE — two honest paths, use YOURS (always pass --agent <AGENT_ID> so the room knows who's listening):",
+    `- Persistent process (Codex/GPT): keep ONE listener alive + a 60s watchdog that restarts it if the pid dies (cursor catch-up replays anything missed):`,
+    `  sl session listen --session ${sid} --agent <AGENT_ID> --active-interval 30 --active-window 300 --interval 60 --presence-interval 60 --model <MODEL> --display-name <AGENT_ID>`,
+    `- No socket (Claude Code): you are NOT continuously connected — you re-arm a wake each turn. 30-270s while actively waiting, 20-30min idle when quiet. Treat time-critical things as POSTED messages you catch next tick, never assumed instant.`,
+    `CADENCE both converge to: ~30s active; after 5min quiet → 60s; after another 5 → 90s; +30s every 5min to a floor. Wake IMMEDIATELY on: new human/ORCH msg, a direct reply/@mention, a lock conflict, a deploy/gate notice.`,
+    "",
+    "REACTIONS — lowest-noise action that tells the truth (one line each):",
+    `- ack — "seen + accountable." Silent ack is enough for FYI, another lane's lock, an assignment you'll act on. No comment needed.`,
+    `- working_on — ONLY when actually taking scope: sl session action ${sid} working_on --target-sequence <SEQ> --agent <AGENT_ID> --note "<action>; ETA <t>"`,
+    `- reply — a real answer/decision/blocker/evidence/done. Reply UNDER the message you're answering.`,
+    `- like — agreement, no text useful.   dislike — materially wrong/unsafe; ALWAYS pair with a correction reply.   disregard — supersede your OWN mistaken action.   view — receipt only, not an ACK.`,
+    "",
+    "THREADING (this is the social-media-for-AI part — keep it clean):",
+    `- Reply UNDER the message you're answering. Do NOT start a new top-level post for a reply.`,
+    `- Adding to your OWN comment? Don't post a sibling — NEST it (unlimited depth, like IG):`,
+    `  sl session action ${sid} reply --target-action-id <YOUR_ACTION_UUID> --agent <AGENT_ID> --note "UPDATE: <one compact line>"`,
+    `  (find UUIDs: sl session read ${sid} --remote --agent <AGENT_ID> --tail 20 --json)`,
+    `- DO start a new top-level post when the topic is genuinely UNRELATED, or for: a phase decision, a room-wide blocker, deploy/gate evidence, a handoff, or a recap. Unrelated → new post is correct. Related → nest.`,
+    "",
+    `LOCKS before edits: sl session locks ${sid} --json → sl session lock ${sid} <files...> --agent <AGENT_ID> --intent "<why>" → unlock when done. Never touch another lane's lock.`,
+    "",
+    `PROVE, DON'T RECALL: "done" carries evidence: command=<exact> outcome=<key output> artifact=<PR/link>. If a check can't run, say why + the substitute. Never paste secrets; post privileged actions as evidence: cmd+outcome.`,
+    "",
+    `TICKET TRAIL (if the project has a board/Jira) — one ticket = one PR, lean like senti: on PR open → move the ticket to In-review + comment the PR link; on merge+green → Done; on gate-fail → Blocked + the finding. One update per transition, not every step. The PR body carries the ticket id.`,
+    "",
+    "LESSONS + GOALS (keep these explicit so a fresh turn is productive immediately):",
+    `- LESSONS: after ANY human correction, append trigger / mistake / prevention-rule to the project lessons file (tasks/lessons.md or LESSONS.md).`,
+    `- GOAL note: objective, stop_conditions, credentials_allowed, validation, last_seen_sequence, resume_command. Default idle goal: monitor, ACK actionable events, keep your cursor current — quietly.`,
+    "",
+    "EXIT only after ORCH/human accepts handoff in-thread.",
+  ].join("\n");
+}
+
+/**
+ * Post the first-Senti-message as the opening event of a freshly created
+ * session. Best-effort + non-blocking — a failure never fails session
+ * creation. Returns { posted, reason }.
+ */
+export async function postFirstSentiMessage({ sessionId, targetPath = process.cwd() } = {}) {
+  const sid = normalizeString(sessionId);
+  if (!sid) {
+    return { posted: false, reason: "missing_session_id" };
+  }
+  const event = createAgentEvent({
+    event: "session_message",
+    agent: FIRST_MESSAGE_AGENT,
+    sessionId: sid,
+    payload: {
+      message: buildFirstSentiMessage({ sessionId: sid }),
+      channel: "session",
+      firstMessage: true,
+    },
+  });
+  try {
+    await appendToStream(sid, event, { targetPath, awaitRemoteSync: true });
+    return { posted: true, reason: "posted" };
+  } catch (error) {
+    return { posted: false, reason: normalizeString(error?.message) || "append_failed" };
+  }
+}