@desplega.ai/agent-swarm 1.145.0 → 1.147.0

package/src/be/users.ts

@@ -529,6 +529,83 @@ export async function resolveUserByToken(plaintext: string): Promise<User | null
   return findUserById(row.userId);
 }
 
+// ---------------------------------------------------------------------------
+// Session tokens (ephemeral, ACP provider)
+// ---------------------------------------------------------------------------
+
+const SESSION_TOKEN_PREFIX = "aseph_"; // agent-swarm-ephemeral
+
+/**
+ * Mint a short-lived `aseph_<base62-24>` token scoped to an ACP session.
+ * The token is handed to the ACP target process instead of the full operator
+ * key; it expires at `now + ttlMs` and is actively revoked when the session
+ * ends.
+ */
+export async function mintSessionToken(
+  agentId: string,
+  taskId: string,
+  ttlMs: number,
+): Promise<{ tokenId: string; plaintext: string }> {
+  const plaintext = `${SESSION_TOKEN_PREFIX}${base62(randomBytes(24))}`;
+  const tokenId = randomUUID().replace(/-/g, "");
+  const hash = sha256Hex(plaintext);
+  const preview = plaintext.slice(-4);
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + ttlMs).toISOString();
+
+  await getDbClient().run(
+    `INSERT INTO session_tokens (id, tokenHash, tokenPreview, agentId, taskId, expiresAt, createdAt)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [tokenId, hash, preview, agentId, taskId, expiresAt, now.toISOString()],
+  );
+
+  return { tokenId, plaintext };
+}
+
+/** Revoke a session token by id. No-op if already revoked. */
+export async function revokeSessionToken(tokenId: string): Promise<void> {
+  await getDbClient().run(
+    "UPDATE session_tokens SET revokedAt = ? WHERE id = ? AND revokedAt IS NULL",
+    [new Date().toISOString(), tokenId],
+  );
+}
+
+/**
+ * Resolve a plaintext `aseph_` token to its principal. Returns null when the
+ * token is unknown, revoked, or past its expiry. On a hit, touches `lastUsedAt`
+ * best-effort.
+ */
+export async function resolveBySessionToken(
+  plaintext: string,
+): Promise<{ agentId: string; taskId: string } | null> {
+  if (!plaintext.startsWith(SESSION_TOKEN_PREFIX)) return null;
+  const hash = sha256Hex(plaintext);
+  const client = getDbClient();
+
+  const row = await client.get<{
+    id: string;
+    agentId: string;
+    taskId: string;
+    expiresAt: string;
+    revokedAt: string | null;
+  }>("SELECT id, agentId, taskId, expiresAt, revokedAt FROM session_tokens WHERE tokenHash = ?", [
+    hash,
+  ]);
+  if (!row || row.revokedAt !== null) return null;
+  if (new Date(row.expiresAt) <= new Date()) return null;
+
+  try {
+    await client.run("UPDATE session_tokens SET lastUsedAt = ? WHERE id = ?", [
+      new Date().toISOString(),
+      row.id,
+    ]);
+  } catch {
+    // best-effort
+  }
+
+  return { agentId: row.agentId, taskId: row.taskId };
+}
+
 // ---------------------------------------------------------------------------
 // API-key fingerprint (operator audit)
 // ---------------------------------------------------------------------------

package/src/commands/attachments-section.ts

@@ -0,0 +1,37 @@
+import { taskAttachmentFetchCommand } from "../utils/task-attachment-links.ts";
+
+/**
+ * Build a ready-to-run fetch recipe for each task attachment, so the agent
+ * can download the bytes in one call via the provider-agnostic
+ * `/api/fs/tasks/{taskId}/files/{attachmentId}/raw` route — instead of having
+ * to discover the file's storage provider/org/drive itself (e.g. guessing at
+ * the `agent-fs` CLI with no org context). MCP_BASE_URL/API_KEY/AGENT_ID are
+ * already present in every worker container's env.
+ */
+export function buildAttachmentsSection(
+  taskId: string | undefined,
+  attachmentsRaw: unknown,
+): string {
+  if (!taskId || !Array.isArray(attachmentsRaw) || attachmentsRaw.length === 0) return "";
+
+  const lines = attachmentsRaw
+    .filter((a): a is Record<string, unknown> => !!a && typeof a === "object")
+    .map((a) => {
+      const id = typeof a.id === "string" ? a.id : undefined;
+      const name = typeof a.name === "string" ? a.name : id;
+      if (!id || !name) return null;
+      const details = [
+        typeof a.mimeType === "string" ? a.mimeType : null,
+        typeof a.sizeBytes === "number" ? `${a.sizeBytes} bytes` : null,
+      ]
+        .filter(Boolean)
+        .join(", ");
+      const cmd = taskAttachmentFetchCommand(taskId, id, name);
+      return `- ${name}${details ? ` (${details})` : ""}: \`${cmd}\``;
+    })
+    .filter((line): line is string => line !== null);
+
+  if (lines.length === 0) return "";
+
+  return `\n\n📎 Attachment(s) — fetch directly, no need to discover the storage path yourself:\n${lines.join("\n")}`;
+}

package/src/commands/claude-managed-setup.ts

@@ -33,6 +33,7 @@ import type { BetaEnvironment } from "@anthropic-ai/sdk/resources/beta/environme
 import type { SkillCreateResponse } from "@anthropic-ai/sdk/resources/beta/skills";
 import { toFile } from "@anthropic-ai/sdk/uploads";
 
+import { buildSkillContent, type SkillTemplateConfig } from "../be/seed-skills/render";
 import { getApiKey } from "../utils/api-key";
 import { promptHiddenInput } from "./codex-login.js";
 
@@ -66,8 +67,20 @@ export type ClaudeManagedSetupResult = {
 
 const DEFAULT_AGENT_MODEL = "claude-sonnet-5";
 const SKILLS_DIR_RELATIVE = "plugin/commands";
+const SEEDED_SKILLS_DIR_RELATIVE = "templates/skills";
 const SKILLS_BETA_HEADER = "skills-2025-10-02";
 
+/**
+ * Seeded skills that must also ship in the managed-agent definition.
+ *
+ * The runner opens every assigned task with `/work-on-task` and every offered
+ * task with `/review-offered-task`. Both live in `templates/skills/` and reach
+ * a normal worker through the DB → filesystem sync. Managed agents run in
+ * Anthropic's sandbox with no entrypoint sync, so they only ever see skills
+ * uploaded here.
+ */
+const SEEDED_SKILLS_TO_UPLOAD = ["work-on-task", "review-offered-task"];
+
 // Config keys persisted to `swarm_config`. The docker-entrypoint hydrates env
 // vars from these on worker boot.
 const CONFIG_KEY_AGENT_ID = "managed_agent_id";
@@ -116,7 +129,8 @@ Options:
 
 This command:
   1. Creates an Anthropic-side environment (cloud, unrestricted networking).
-  2. Uploads each plugin/commands/*.md as a managed-agents skill (skips on 409).
+  2. Uploads each plugin/commands/*.md plus the turn-prompt skills under
+     templates/skills/ as managed-agents skills (skips on 409).
   3. Creates a managed-agents agent referencing the uploaded skills + the
      swarm MCP server (MCP_BASE_URL/mcp).
   4. Persists the resulting IDs to swarm_config (managed_agent_id,
@@ -211,6 +225,26 @@ async function loadSkillFiles(
   return out;
 }
 
+/**
+ * Load `SEEDED_SKILLS_TO_UPLOAD` from `templates/skills/<name>/` and render
+ * each as a SKILL.md, using the same frontmatter renderer the seeder uses.
+ */
+async function loadSeededSkillFiles(
+  templatesDir: string,
+  names: string[] = SEEDED_SKILLS_TO_UPLOAD,
+): Promise<Array<{ slug: string; absPath: string; content: string }>> {
+  const out: Array<{ slug: string; absPath: string; content: string }> = [];
+  for (const name of names) {
+    const dir = path.join(templatesDir, name);
+    const config = JSON.parse(
+      await readFile(path.join(dir, "config.json"), "utf8"),
+    ) as SkillTemplateConfig;
+    const body = await readFile(path.join(dir, "content.md"), "utf8");
+    out.push({ slug: name, absPath: dir, content: buildSkillContent(config, body) });
+  }
+  return out;
+}
+
 async function uploadSkill(
   client: Anthropic,
   slug: string,
@@ -438,8 +472,10 @@ export type RunClaudeManagedSetupDeps = {
   fetchConfig?: typeof fetchConfigByKey;
   upsert?: typeof upsertConfig;
   loadSkills?: typeof loadSkillFiles;
+  loadSeededSkills?: typeof loadSeededSkillFiles;
   uploadOne?: typeof uploadSkill;
   skillsDir?: string;
+  seededSkillsDir?: string;
   log?: (msg: string) => void;
 };
 
@@ -459,8 +495,11 @@ export async function runClaudeManagedSetupFlow(
   const fetchCfg = deps.fetchConfig ?? fetchConfigByKey;
   const upsert = deps.upsert ?? upsertConfig;
   const loadSkills = deps.loadSkills ?? loadSkillFiles;
+  const loadSeededSkills = deps.loadSeededSkills ?? loadSeededSkillFiles;
   const uploadOne = deps.uploadOne ?? uploadSkill;
   const skillsDir = deps.skillsDir ?? path.resolve(process.cwd(), SKILLS_DIR_RELATIVE);
+  const seededSkillsDir =
+    deps.seededSkillsDir ?? path.resolve(process.cwd(), SEEDED_SKILLS_DIR_RELATIVE);
 
   // Idempotency check: if an agent ID is already persisted, short-circuit
   // unless --force was passed.
@@ -495,8 +534,11 @@ export async function runClaudeManagedSetupFlow(
   log(`  + environment id=${env.id}`);
 
   // 2. Upload skills.
-  log(`Uploading skills from ${skillsDir} ...`);
-  const skillFiles = await loadSkills(skillsDir);
+  log(`Uploading skills from ${skillsDir} and ${seededSkillsDir} ...`);
+  const skillFiles = [
+    ...(await loadSkills(skillsDir)),
+    ...(await loadSeededSkills(seededSkillsDir)),
+  ];
   log(`  found ${skillFiles.length} skill markdown file(s)`);
   // Pre-fetch existing custom skills so we can reuse their IDs on rerun. The
   // API returns 400 (not 409) on display_title collision and skill IDs aren't

package/src/commands/claude-md-session.ts

@@ -0,0 +1,408 @@
+/**
+ * The Claude hook's handling of the SHARED personal CLAUDE.md
+ * (`~/.claude/CLAUDE.md`) across concurrent sessions of one agent.
+ *
+ * Every SessionStart backs the current file up to `.bak` and materializes the
+ * DB value into it; every Stop syncs the file back and restores the `.bak`.
+ * Sessions of one agent overlap, so what a Stop finds on disk can be an agent's
+ * edit, or content a hook wrote — this session's or a sibling's materialization,
+ * or a `.bak` restore (Stop can fire more than once). Syncing hook-written
+ * content can revert a value the DB already moved past — measured: `claudeMd`
+ * edits reverted 8–27 s later, byte-for-byte to the previous version.
+ *
+ * So the hook keeps a LINEAGE record for the file, rewritten on every hook write:
+ *   - `written`: hash of the content the hook itself put there, or null when it
+ *     restored an agent's edit. A file that still hashes to it is not an edit
+ *     and is never synced.
+ *   - `base`: hash of the DB value that content derives from. An edit is sent
+ *     with it as the compare-and-set token (`expectedHashes.claudeMd`): the
+ *     server applies it if the DB is still at that value — including a
+ *     deliberate revert to an earlier version — and drops it otherwise.
+ * The `.bak` carries the same two facts in a sidecar, so restoring an agent's
+ * unsynced edit that a sibling's SessionStart had backed up brings back an edit
+ * (still synced, against its own base), not something a hook wrote.
+ *
+ * Transitions of the pair (file + record) run under one kernel-held
+ * cross-process lock (`src/utils/file-lock.ts`, flock): SessionStart's
+ * materialization, the Stop's whole read → sync → restore protocol, and the
+ * runner backstop's read + post. Without it a Stop landing between the file
+ * write and the record write reads a mismatched pair and can re-create the
+ * revert this module exists to prevent. The lock can never be taken from a live
+ * holder, so no transition ever runs without it:
+ *   - lock busy (or failing) → the transition is skipped, never run unlocked.
+ *     A skipped SessionStart leaves the file as it is (whatever is there carries
+ *     its own lineage); a skipped Stop pushes and restores nothing.
+ *   - no flock on this platform → SessionStart still materializes (unprotected)
+ *     but no Stop ever pushes: the DB is never at risk. An edit a Stop would
+ *     have sent is saved instead (see below).
+ * The record and the sidecar are also written atomically (temp file + rename),
+ * and an unreadable record counts as hook-written, never as a reason to push.
+ * A write that fails fails closed, the same way: every hook write marks the
+ * record pending BEFORE touching the file, naming the content it writes, and
+ * the real lineage replaces the marker after. A pending record makes whatever
+ * is on disk hook-written, for the Stop and the runner backstop alike, so:
+ *   - the marker cannot be written → the transition is skipped (SessionStart
+ *     throws, a Stop restores nothing), as with a busy lock;
+ *   - the real lineage cannot replace it → the marker stays: an edit made on
+ *     top of that file is never pushed, since its base is unknown.
+ * Such an edit is never discarded silently either. Before a hook overwrites or
+ * deletes content it did not push and whose lineage is unknown (a pending
+ * marker naming other content, an unreadable record, or an edit where there is
+ * no flock), it saves a copy as `CLAUDE.md.unsynced-<hash>` and warns; if the
+ * copy fails, it leaves the file alone. Bringing the copy into the DB is a
+ * manual step. The next hook write whose lineage lands heals the record.
+ * A Stop with no `.bak` removes the record only once the file is gone.
+ *
+ * Known limit: with one `.bak` slot, a third overlapping session overwrites the
+ * backup of the first, and a Stop can restore a backup a sibling took (as before
+ * this module); both are disk-level only, since every copy carries its lineage.
+ */
+
+// `rename` has no Bun equivalent; it is what makes the record writes atomic.
+import { rename } from "node:fs/promises";
+import { withFileLock } from "../utils/file-lock.ts";
+import { scrubSecrets } from "../utils/secret-scrubber.ts";
+import {
+  CLAUDE_MD_LINEAGE_PATH,
+  CLAUDE_MD_LOCK_PATH,
+  CLAUDE_MD_PATH,
+  type ClaudeMdLineage,
+  claudeMdLineageOf,
+  claudeMdPendingRecord,
+  contentSha256,
+  effectiveClaudeMdLineage,
+  type FileReader,
+  hookWrittenLineage,
+  type ProfilePayload,
+  parseClaudeMdLineage,
+  parseClaudeMdPendingRecord,
+  planClaudeMdSync,
+} from "./profile-sync.ts";
+
+export { planClaudeMdSync };
+
+export interface ClaudeMdSessionPaths {
+  /** The shared personal CLAUDE.md. */
+  file: string;
+  /** Where SessionStart backs up the previous content; Stop restores it. */
+  backup: string;
+  /** Lineage record of the content the hook last wrote to `file`. */
+  record: string;
+  /** Cross-process lock for every transition of `file` + `record`. */
+  lock: string;
+}
+
+const readText: FileReader = async (path) => {
+  const file = Bun.file(path);
+  return (await file.exists()) ? await file.text() : undefined;
+};
+
+export const DEFAULT_CLAUDE_MD_SESSION_PATHS: ClaudeMdSessionPaths = {
+  file: CLAUDE_MD_PATH,
+  backup: `${CLAUDE_MD_PATH}.bak`,
+  record: CLAUDE_MD_LINEAGE_PATH,
+  lock: CLAUDE_MD_LOCK_PATH,
+};
+
+/**
+ * How long each side waits for the lock, both below the Claude Code hook timeout
+ * (60 s). SessionStart waits longer: giving up means the session starts with
+ * whatever CLAUDE.md is already on disk.
+ */
+const SESSION_START_LOCK_WAIT_MS = 40_000;
+const STOP_LOCK_WAIT_MS = 15_000;
+
+/**
+ * Test seam: pause points inside a transition, to force interleavings — or, by
+ * throwing, a failure of the step that follows.
+ */
+export interface ClaudeMdTestPauses {
+  afterFileWrite?: () => Promise<void>;
+  /** Right before the real lineage replaces the pending marker. */
+  beforeRecordCommit?: () => Promise<void>;
+}
+
+/**
+ * Write via a temp file in the same directory plus `rename`: readers see the old
+ * content or the new one, never a partial write. `rename` also replaces a
+ * symlink at `path` instead of writing through it.
+ */
+async function writeAtomic(path: string, data: string): Promise<void> {
+  const tmp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  await Bun.write(tmp, data);
+  try {
+    await rename(tmp, path);
+  } catch (error) {
+    await Bun.file(tmp)
+      .delete()
+      .catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * The one way a hook write reaches the file: mark the record pending (naming
+ * the content), write the content, then replace the marker with its lineage.
+ * The marker failing throws before the file is touched; the lineage failing is
+ * logged, not thrown: the file is already in place and the marker keeps it
+ * unpushable.
+ */
+async function writeUnderPendingRecord(
+  paths: ClaudeMdSessionPaths,
+  pauses: ClaudeMdTestPauses,
+  content: string,
+  lineage: ClaudeMdLineage,
+): Promise<void> {
+  await writeAtomic(paths.record, claudeMdPendingRecord(contentSha256(content)));
+  await Bun.write(paths.file, content); // creates ~/.claude if missing
+  await pauses.afterFileWrite?.();
+  try {
+    await pauses.beforeRecordCommit?.();
+    await writeAtomic(paths.record, JSON.stringify(lineage));
+  } catch (error) {
+    console.warn(
+      scrubSecrets(`[claude-md] lineage not recorded, the file stays unpushable: ${String(error)}`),
+    );
+  }
+}
+
+/**
+ * Whether `content` may be an agent's edit whose base is unknown: the record is
+ * there but is no lineage — a pending marker naming other content, or an
+ * unreadable record. Such content is never pushed, so it must not be discarded.
+ * Blank content counts: clearing the file is an edit too, and one that is never
+ * pushed at all (`planClaudeMdSync` skips it), so the copy is the only record of
+ * it. No record at all is excluded: that content is pushed, not saved.
+ */
+function hasUnknownLineage(content: string, rawRecord: string | undefined): boolean {
+  if (rawRecord === undefined) return false;
+  if (parseClaudeMdLineage(rawRecord)) return false;
+  return parseClaudeMdPendingRecord(rawRecord) !== contentSha256(content);
+}
+
+/** Where a hook saves content it can neither push nor keep: one file per content. */
+export function unsyncedCopyPath(paths: ClaudeMdSessionPaths, content: string): string {
+  return `${paths.file}.unsynced-${contentSha256(content).slice(0, 12)}`;
+}
+
+/**
+ * Save content that cannot be pushed before a hook discards it; throws if it
+ * cannot. The copy may hold an agent's edit, or not (a partial write, content a
+ * failed write left behind): its base is unknown either way, so it is never
+ * something to re-apply blindly.
+ */
+async function saveUnsynced(paths: ClaudeMdSessionPaths, content: string): Promise<void> {
+  const copy = unsyncedCopyPath(paths, content);
+  await writeAtomic(copy, content);
+  console.warn(
+    scrubSecrets(
+      `[claude-md] CLAUDE.md content of unknown lineage was not synced; saved to ${copy} ` +
+        "instead of discarding it. It may hold an agent's edit: compare it with the current " +
+        "value before re-applying anything.",
+    ),
+  );
+}
+
+/** Delete `path`: already gone is fine, any other failure throws. */
+async function deleteIfPresent(path: string): Promise<void> {
+  try {
+    await Bun.file(path).delete();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+/** Why a transition did not run under the lock; see `FileLockResult`. */
+type LockMiss = "busy" | "error" | "unsupported";
+
+function warnLockMiss(step: string, miss: { reason: LockMiss; error?: unknown }): void {
+  const detail = miss.error === undefined ? "" : `: ${String(miss.error)}`;
+  console.warn(scrubSecrets(`[claude-md] no lock at ${step} (${miss.reason})${detail}`));
+}
+
+/** `unsupported`: materialized anyway, without protection (see the module header). */
+export type ClaudeMdMaterializeOutcome = "materialized" | LockMiss;
+
+/**
+ * SessionStart: under the lock, back up whatever is on disk together with its
+ * lineage, then materialize the DB value and record it. Lock busy or failing →
+ * nothing is written (the file is left as it is). No flock on this platform →
+ * materialized without protection; `stopClaudeMd` then never pushes. Throws,
+ * leaving the file and its record as they were, if the record cannot be marked
+ * pending or an unsynced edit on disk cannot be saved.
+ */
+export async function materializeClaudeMd(
+  content: string,
+  paths: ClaudeMdSessionPaths = DEFAULT_CLAUDE_MD_SESSION_PATHS,
+  options: { testPauses?: ClaudeMdTestPauses; lockWaitMs?: number } = {},
+): Promise<ClaudeMdMaterializeOutcome> {
+  const pauses = options.testPauses ?? {};
+  const locked = await withFileLock(paths.lock, () => materializeUnlocked(content, paths, pauses), {
+    waitMs: options.lockWaitMs ?? SESSION_START_LOCK_WAIT_MS,
+  });
+  if (locked.acquired) return "materialized";
+  warnLockMiss("SessionStart", locked);
+  if (locked.reason === "unsupported") await materializeUnlocked(content, paths, pauses);
+  return locked.reason;
+}
+
+async function materializeUnlocked(
+  content: string,
+  paths: ClaudeMdSessionPaths,
+  pauses: ClaudeMdTestPauses,
+): Promise<void> {
+  const state = await readClaudeMdSyncState(paths);
+  if (state) {
+    const { content: existing, record } = state;
+    if (state.lineageUnknown) await saveUnsynced(paths, existing);
+    // With a record, anything but the hook's own write is an agent's unsynced
+    // edit. Without one (the file predates the hook, e.g. the user's own) its
+    // origin is unknown: treat it as hook-written, never to be pushed.
+    const lineage = record ? claudeMdLineageOf(existing, record) : hookWrittenLineage(existing);
+    await Bun.write(paths.backup, existing);
+    // `of` pins the sidecar to this exact backup: a stale sidecar left by an
+    // earlier overlap must not describe a different `.bak`.
+    const sidecar = { ...lineage, of: contentSha256(existing) };
+    await writeAtomic(`${paths.backup}.lineage`, JSON.stringify(sidecar)).catch(() => {});
+  }
+  const hash = contentSha256(content);
+  await writeUnderPendingRecord(paths, pauses, content, { written: hash, base: hash });
+}
+
+/**
+ * Restore the `.bak` with its lineage (or remove the file if there was none).
+ * Throws, having restored nothing, if the record cannot be marked pending.
+ */
+async function restoreUnlocked(
+  paths: ClaudeMdSessionPaths,
+  pauses: ClaudeMdTestPauses,
+): Promise<void> {
+  const backup = Bun.file(paths.backup);
+  const sidecar = Bun.file(`${paths.backup}.lineage`);
+  if (await backup.exists()) {
+    const content = await backup.text();
+    const raw = (await sidecar.exists()) ? await sidecar.text() : undefined;
+    let lineage: ClaudeMdLineage | null = null;
+    try {
+      const pinnedTo = raw ? (JSON.parse(raw) as { of?: unknown }).of : undefined;
+      if (pinnedTo === contentSha256(content)) lineage = parseClaudeMdLineage(raw);
+    } catch {
+      lineage = null; // corrupt sidecar: unknown lineage
+    }
+    // Without a matching sidecar (a legacy `.bak`, a failed or stale sidecar)
+    // the lineage is unknown: record it as hook-written, the conservative choice
+    // (never pushed as an edit).
+    await writeUnderPendingRecord(paths, pauses, content, lineage ?? hookWrittenLineage(content));
+    // Only after the lineage: a `.bak` that cannot be deleted must not cost a
+    // restored edit its lineage. (A leftover `.bak` is restored again, harmlessly.)
+    await backup.delete();
+    await sidecar.delete().catch(() => {});
+  } else {
+    // The record goes only once the file is gone: a file left without its
+    // record would be sent unconditionally by the next Stop.
+    await deleteIfPresent(paths.file);
+    await deleteIfPresent(paths.record).catch(() => {});
+  }
+}
+
+/**
+ * What a Stop must save before its restore discards the file: content of
+ * unknown lineage (never pushed), or, when the Stop could not push at all (no
+ * flock), an edit it would have sent.
+ */
+function unpushedContent(state: ClaudeMdSyncState | null, couldPush: boolean): string | null {
+  if (!state) return null;
+  if (state.lineageUnknown) return state.content;
+  return !couldPush && planClaudeMdSync(state) ? state.content : null;
+}
+
+/**
+ * Save `unpushed` (see `unpushedContent`), then restore; if the save fails the
+ * restore is skipped and the file stays. A Stop never fails over its restore:
+ * it is logged, and the rest of Stop runs.
+ */
+async function restoreSavingUnpushed(
+  paths: ClaudeMdSessionPaths,
+  pauses: ClaudeMdTestPauses,
+  unpushed: string | null,
+): Promise<void> {
+  try {
+    if (unpushed !== null) await saveUnsynced(paths, unpushed);
+    await restoreUnlocked(paths, pauses);
+  } catch (error) {
+    console.warn(scrubSecrets(`[claude-md] .bak not restored: ${String(error)}`));
+  }
+}
+
+export interface ClaudeMdSyncState {
+  /** Current content of the shared file. */
+  content: string;
+  /** Lineage record of the last hook write, or null if there is none. */
+  record: ClaudeMdLineage | null;
+  /** The record is there but is no lineage for this content: never pushed, never discarded. */
+  lineageUnknown: boolean;
+}
+
+/** Read what the Stop sync needs to decide; null when the file does not exist. */
+export async function readClaudeMdSyncState(
+  paths: ClaudeMdSessionPaths = DEFAULT_CLAUDE_MD_SESSION_PATHS,
+  readFile: FileReader = readText,
+): Promise<ClaudeMdSyncState | null> {
+  const content = await readFile(paths.file);
+  if (content === undefined) return null;
+  const raw = await readFile(paths.record);
+  return {
+    content,
+    record: effectiveClaudeMdLineage(raw, content),
+    lineageUnknown: hasUnknownLineage(content, raw),
+  };
+}
+
+/** `unsupported`: the `.bak` was restored, but nothing is ever pushed there. */
+export type ClaudeMdStopOutcome = "synced" | "not-an-edit" | LockMiss;
+
+/**
+ * Stop: under the lock, decide the sync from what is on disk, run it, then
+ * restore the `.bak` — one transition, so no SessionStart can land in between.
+ * Lock busy or failing → nothing is pushed or restored (safe: the next
+ * SessionStart backs up whatever is there, with its lineage). No flock on this
+ * platform → the `.bak` is restored as before, but nothing is ever pushed (an
+ * edit it would have sent is saved first). A restore that fails is logged,
+ * never thrown.
+ */
+export async function stopClaudeMd(
+  sync: (body: ProfilePayload["body"]) => Promise<void>,
+  paths: ClaudeMdSessionPaths = DEFAULT_CLAUDE_MD_SESSION_PATHS,
+  options: { testPauses?: ClaudeMdTestPauses; lockWaitMs?: number } = {},
+): Promise<ClaudeMdStopOutcome> {
+  const pauses = options.testPauses ?? {};
+  const locked = await withFileLock(
+    paths.lock,
+    async (): Promise<ClaudeMdStopOutcome> => {
+      const state = await readClaudeMdSyncState(paths);
+      const body = state ? planClaudeMdSync(state) : null;
+      if (body) {
+        await sync(body).catch((error: unknown) => {
+          console.warn(scrubSecrets(`[claude-md] sync failed: ${String(error)}`));
+        });
+      }
+      await restoreSavingUnpushed(paths, pauses, unpushedContent(state, true));
+      return body ? "synced" : "not-an-edit";
+    },
+    { waitMs: options.lockWaitMs ?? STOP_LOCK_WAIT_MS },
+  );
+  if (locked.acquired) return locked.value;
+  warnLockMiss("Stop", locked);
+  if (locked.reason === "unsupported") {
+    // Nothing is pushed without the lock: an edit this Stop would have sent is
+    // saved instead of being discarded by the restore. Unreadable → no restore.
+    const state = await readClaudeMdSyncState(paths).catch((error: unknown) => {
+      console.warn(scrubSecrets(`[claude-md] .bak not restored: ${String(error)}`));
+      return undefined;
+    });
+    if (state !== undefined) {
+      await restoreSavingUnpushed(paths, pauses, unpushedContent(state, false));
+    }
+  }
+  return locked.reason;
+}

package/src/commands/context-preamble.ts

@@ -2,9 +2,9 @@
  * Universal context preamble for follow-up task continuity.
  *
  * Builds a bounded text summary of prior task context (parent → ancestor chain)
- * and prepends it to the child task's prompt. This makes follow-up continuity
- * uniform across ALL harness providers — not just those that support native
- * session resume (claude/codex).
+ * and inserts it after the child task's leading skill invocation. This makes
+ * follow-up continuity uniform across ALL harness providers — not just those
+ * that support native session resume (claude/codex).
  *
  * Token budget (CONTEXT_PREAMBLE_MAX_TOKENS, default 2000) prevents the
  * SIGTERM-143 context-saturation failure mode seen with unbounded session
@@ -16,6 +16,18 @@ import { scrubSecrets } from "../utils/secret-scrubber";
 import { isSteeringEnabled } from "../utils/steering-enabled";
 import { taskAttachmentDisplayUrl } from "../utils/task-attachment-links";
 
+/** Keep slash skills on line one so native and adapter resolvers can expand them. */
+export function prependContextPreamble(prompt: string, preamble: string): string {
+  if (!preamble) return prompt;
+  const newline = prompt.indexOf("\n");
+  const firstLine = newline === -1 ? prompt : prompt.slice(0, newline);
+  if (!/^\/[a-z0-9:_-]+(?:[ \t].*)?$/.test(firstLine.trim())) {
+    return preamble + prompt;
+  }
+  const rest = newline === -1 ? "" : prompt.slice(newline + 1);
+  return `${firstLine}\n${preamble}${rest}`;
+}
+
 export const CONTEXT_PREAMBLE_MAX_TOKENS = Number(
   process.env.CONTEXT_PREAMBLE_MAX_TOKENS || "2000",
 );