Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat: add RASMIC orchestration memory automation

Rahman15effa71bf37
diff --git a/README.md b/README.md
index 5fb4a126..61c0b2e4 100644
--- a/README.md
+++ b/README.md
@@ -80,6 +80,7 @@ For a real deployment, put MSO behind **Tailscale, a VPN, or a TLS reverse proxy
- **Spawn focused same-session subagents** — `/spawn` and `agent_subagent_run` create bounded foreground workers with isolated context, explicit delegated scope, turn/timeout caps, no recursive spawn, and final-result-only return. They are not Local Agent peers and do not run autonomously after the parent call returns. See [Subagents](./docs/SUBAGENTS.md).
- **Delegate between remote agents with standard A2A v1** — register public HTTPS peers, attach private API-key/Bearer/OAuth access-token profiles, stream remote tasks over SSE, or expose MSO's authenticated inbound Agent Card when a public HTTPS origin is configured. Inbound credentials are owner-minted `read | write | exec` capabilities and run in a memory-isolated task context. See [A2A](./docs/A2A.md).
- **Keep agents efficient independently of the model provider** — the MCP-first [Cognitive Runtime](./docs/COGNITIVE-RUNTIME.md) isolates conversations from OAuth identity, budgets model context/tool output, selects a compact per-turn capability set without weakening scopes, compacts durable sessions with sanitized 30-day backup archives, and learns only verified workflow recipes. `bun run bench:cognitive` guards routing recall and context footprint.
+- **Make orchestration risk-aware and self-improving** — [RASMIC](./docs/RASMIC.md) classifies task risk/contention, retrieves compact repo-local memory, records manual user tests and Evidence Receipts, detects path/shared-resource collisions before merge conflicts, and promotes repeated safe routes from observed traces → recipes → tested bounded scripts.
- **Add app slices** — features are modular under `frontend/slices/<slug>/`.
- **Personalize the interface** — macOS, Windows, iOS, and Android shell layouts are UI preferences, not the core product.
diff --git a/docs/RASMIC.md b/docs/RASMIC.md
new file mode 100644
index 00000000..ba31dc00
--- /dev/null
+++ b/docs/RASMIC.md
@@ -0,0 +1,137 @@
+# RASMIC — Risk-Aware Orchestration, Memory, Evidence, and Automation
+
+RASMIC is MSO's model-independent orchestration layer. It decides how much safety, memory, verification, and automation a task needs. It is part of MSO itself and has no hard dependency on another repository, vendor, model provider, or external memory service.
+
+## Runtime flow
+
+```text
+TASK
+→ CLASSIFY (complexity · risk · contention · memory relevance)
+→ PREPARE (minimal memory · recipe/script · collision check · isolate if useful)
+→ EXECUTE (bounded tools · tested scripts · agents when useful)
+→ VERIFY (progressive tests · Evidence Receipt · health/manual evidence)
+→ LEARN (task/debug/test/failure memory · recipe quality · script promotion)
+```
+
+## Risk and isolation
+
+| Risk | Examples | Default isolation | Verification |
+| --- | --- | --- | --- |
+| LOW | docs, typo, isolated minor UI/style | direct | targeted |
+| MEDIUM | contained feature, vertical slice, multi-file/runtime change | optional short-lived branch/worktree | affected checks |
+| HIGH | auth, schema/database, destructive operation, infra/deploy, secrets, public API, dependency upgrade, broad/multi-agent refactor | isolated worktree | full/progressive |
+
+A branch/worktree is a safety mechanism, not a goal. `main` can remain the integration state. New high-risk workflows cannot claim success without explicit verification evidence.
+
+## Task context and collision detection
+
+`workflow_start` accepts optional `affected_paths` and `reserved_resources`. Resource labels can be `port:4173`, `database:development`, `deployment:staging`, `queue:jobs`, etc.
+
+The orchestration snapshot records base commit/branch when available, workspace path, current changed paths, declared affected paths/resources, overlapping paths/resources, active/conflicting workflow counts, risk/complexity/contention, isolation/verification policy, cleanup state, memory hits, approximate context tokens, and reused recipe id.
+
+Collision summaries intentionally do not reveal another session's private actor or intent.
+
+A worktree isolates Git/filesystem state only. Ports, databases, APIs, queues, caches, Docker services, deployment targets, and lockfile semantics remain explicit shared resources.
+
+## Progressive verification
+
+```text
+LOW: targeted check
+MEDIUM: targeted check → affected tests → build if affected
+HIGH: targeted check → affected tests → build → broader regression → E2E/release verification when applicable
+```
+
+## Evidence Receipt
+
+`workflow_finish` accepts additive structured evidence: claims, tests, build, deployment, health, artifacts, manual verification, environment, and known risks. Receipts can include base/final commit.
+
+A successful tool call is not proof that the user-facing result works. New HIGH-risk workflows require concrete test/build/deployment/health/manual evidence before `success: true` is accepted. Evidence is redacted before persistence.
+
+## Repo-local memory
+
+```text
+.agent/
+├── memory/
+│ ├── tasks/
+│ ├── debug/
+│ ├── tests/
+│ ├── decisions/
+│ └── failures/
+├── recipes/
+├── scripts/
+└── evidence/
+```
+
+Memory is compact structured JSON, not raw chat history. It distills what happened, what was learned, what failed, what worked, and what should be reused.
+
+Lifecycle: `active → confirmed → superseded → archived`.
+
+Retrieval combines lexical relevance, confidence, importance, freshness, lifecycle, and manual-user authority. Superseded/archived records are excluded by default, stale records lose rank, and a current failed manual user test outranks a conflicting automated healthy assumption. `project_memory_search` is read-only and does not create `.agent/` merely because an agent searched. `project_memory_upsert` writes one task/debug/test/decision/failure record. LOW trivial successful tasks remain memory-light unless explicit evidence or relevant memory warrants persistence.
+
+## Manual user tests
+
+User evidence is first-class. A report such as “I tested it and it still freezes” should be stored as:
+
+```text
+kind: test
+source: user-manual
+result: fail
+observation: <actual user observation>
+```
+
+A newer failed manual test must not be silently overridden by an older automated pass. The terminal tool router loads repo-memory tools for natural test/debug/regression wording such as `tested`, `freezes`, `crashed`, and `failed`.
+
+## Recipe → script lifecycle
+
+```text
+observed trace
+→ repeated success
+→ reusable recipe candidate
+→ stable verified recipe
+→ bounded deterministic script candidate
+→ successful real replay
+→ tested script
+```
+
+A one-off trace may remain searchable history but is not returned as a reusable `recommendedRecipe`. Automatic script replay is currently restricted to bounded read-only tools. Write/exec routes remain recipes requiring normal reasoning, approval, and verification.
+
+`project_script_run` re-validates every manifest step. A tampered script containing write/exec tools is refused. Candidate scripts become `tested` only after a successful real replay, not because unrelated workflow evidence exists. Outputs are compact and structured so repeated deterministic checks can collapse several model/tool turns into one call.
+
+## Review loop
+
+`review → classify actionable findings → fix → test → review again`.
+
+Stop on `maxIterations`, repeated no-progress, new regressions, destructive uncertainty, or required human decision. Static analysis, tests, security scans, architecture rules, LLM reviewers, and external reviewers are optional backends; none is mandatory.
+
+## Metrics
+
+`workflow_finish` reports tool calls, execution duration, retries, memory hits, approximate context tokens, recipe reuse/stage, and whether a script candidate was created. The objective is repeated reasoning ↓, tool calls ↓, context usage ↓, consistency ↑.
+
+## Security
+
+RASMIC redacts common token/password/API-key/Authorization/private-key/credential-query forms. `.agent` must be a real directory, not a symlink escape. JSON writes are atomic and bounded to 64 KiB. Created files/directories use owner-only modes. Artifact and caller-provided memory ids are normalized to safe basenames. Nested `.agent` symlink escapes are refused during both reads and writes. Script execution rechecks read-only scope. Do not persist raw credentials, cookies, Authorization headers, private keys, or secret-bearing command bodies.
+
+## Backward compatibility
+
+RASMIC is additive. Existing workflow ids and learned recipe storage remain valid; old in-flight workflows without RASMIC metadata can close under the old finish contract; new start fields and finish evidence are optional additions; `.agent` is portable/optional; no new package dependency is required.
+
+## Future optional API
+
+Repo-local memory stays canonical. A future service can map to `memory.search`, `memory.get`, `memory.related`, `memory.timeline`, `memory.upsert`, `memory.supersede`, `recipe.find`, and `script.find` without becoming a core dependency.
+
+## MCP surfaces
+
+- `workflow_start`: classify, collision check, minimal memory/recipe/script retrieval.
+- `workflow_finish`: Evidence Receipt, memory, recipe quality, metrics, script-candidate promotion.
+- `project_memory_search`: ranked repo-local retrieval.
+- `project_memory_upsert`: structured memory and manual-test ingestion.
+- `project_script_run`: bounded read-only replay and candidate→tested promotion.
+
+## Simple mental model
+
+```text
+Small task → do it directly → targeted test.
+Bigger task → check risk/collisions → retrieve only useful old lessons → use recipe/tested script if available → isolate if justified → work → test → save evidence/lessons.
+```
+
+The engineering ceremony stays behind the user-facing workflow.
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index 40fec9a2..077578c6 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -42,6 +42,9 @@ const MCP_ONLY: Record<string, string> = {
"workflow.status": "app-only MCP Apps bridge used by the ChatGPT progress component; Alfa already owns its in-shell run state and must not poll the external workflow store",
"workflow.cancel": "same actor-scoped boundary; external runs need explicit recovery from an interrupted task",
"workflow.finish": "same actor-scoped learning loop; Alfa recipes can use the session route later without weakening MCP scope semantics",
+ "project.memory.search": "repo-local RASMIC orchestration memory belongs to the terminal/external workflow harness; Alfa intentionally keeps its separate owner recall and must not collapse those memory principals",
+ "project.memory.upsert": "same repo-local RASMIC ledger; writes are workflow-scoped/audited for external agents rather than shared with Alfa owner recall",
+ "project.script.run": "RASMIC script replay is an external/terminal orchestration primitive that revalidates bounded read-only steps and may promote candidate metadata; Alfa has no matching workflow/script lifecycle",
"agent.session.current": "external MCP clients need a stable durable MSO session id they can quote from a later ChatGPT conversation; in-shell Alfa already owns its conversation identity",
"agent.sessions.list": "external MCP clients need explicit cross-conversation session discovery; Alfa's in-app thread UI already provides its own conversation list",
"agent.session.resume": "external MCP clients must reconstruct only the safe MSO resume packet across ChatGPT conversations; Alfa can reopen its own persisted in-app thread directly",
@@ -140,6 +143,9 @@ describe("MCP rate limits mirror the routes", () => {
// MCP clients and is expensive enough to deserve a much smaller bucket.
"screen.capture": 10,
"workflow.memory": 30,
+ "project.memory.search": 60,
+ "project.memory.write": 60,
+ "project.script.run": 30,
// workflow_status is app-only polling. Keep its own bucket so UI refreshes
// neither consume lifecycle capacity nor bypass the server-wide token limit.
"workflow.status": 30,
diff --git a/lib/mcp/tools-learning.test.ts b/lib/mcp/tools-learning.test.ts
index 0a6fa305..9d043299 100644
--- a/lib/mcp/tools-learning.test.ts
+++ b/lib/mcp/tools-learning.test.ts
@@ -153,4 +153,119 @@ describe("workflow_start bootstrap", () => {
await expect(activeWorkflowForActor(context.actor)).resolves.toBeNull();
});
+ it("classifies high-risk work, requires evidence, and persists a repo-local receipt plus task memory", async () => {
+ const start = LEARNING_TOOLS.find((tool) => tool.name === "workflow_start")!;
+ const finish = LEARNING_TOOLS.find((tool) => tool.name === "workflow_finish")!;
+ const context = { actor: "mcp:rasmic-high", scope: "write" as const };
+ const started = await start.run({
+ intent: "update authentication and database schema before production deployment",
+ project,
+ }, context) as {
+ workflow: { id: string; orchestration?: { risk: string; isolation: string } };
+ bootstrap: { orchestration: { classification: { risk: string; isolation: string; verification: string } } };
+ };
+ expect(started.workflow.orchestration).toMatchObject({ risk: "high", isolation: "isolated-worktree" });
+ expect(started.bootstrap.orchestration.classification).toMatchObject({
+ risk: "high", isolation: "isolated-worktree", verification: "full",
+ });
+
+ await expect(finish.run({
+ workflow_id: started.workflow.id, summary: "done", success: true,
+ }, context)).rejects.toThrow(/requires explicit/i);
+ const { activeWorkflowForActor } = await import("@/lib/skills/memory");
+ await expect(activeWorkflowForActor(context.actor, started.workflow.id)).resolves.toMatchObject({ id: started.workflow.id });
+
+ const done = await finish.run({
+ workflow_id: started.workflow.id,
+ summary: "auth/schema change verified",
+ success: true,
+ evidence: { tests: ["targeted auth/schema regression passed"], manual_verification: ["smoke verification passed"] },
+ }, context) as {
+ evidence: { valid: boolean; path?: string };
+ repoMemory: { taskMemoryId?: string; warnings: string[] };
+ };
+ expect(done.evidence.valid).toBe(true);
+ expect(done.evidence.path).toMatch(/^\.agent\/evidence\//);
+ expect(done.repoMemory.taskMemoryId).toMatch(/^mem_/);
+ expect(done.repoMemory.warnings).toEqual([]);
+ expect((await fs.readdir(path.join(project, ".agent/evidence"))).length).toBeGreaterThan(0);
+ expect((await fs.readdir(path.join(project, ".agent/memory/tasks"))).length).toBeGreaterThan(0);
+ });
+
+ it("records a user manual failed test through the public project memory tool", async () => {
+ const upsert = LEARNING_TOOLS.find((tool) => tool.name === "project_memory_upsert")!;
+ const search = LEARNING_TOOLS.find((tool) => tool.name === "project_memory_search")!;
+ const context = { actor: "mcp:rasmic-manual", scope: "write" as const };
+ const record = await upsert.run({
+ project, kind: "test", title: "Reconnect smoke",
+ summary: "user reports the runtime still freezes after reconnect",
+ observation: "user reports the runtime still freezes after reconnect",
+ source: "user-manual", result: "fail", environment: "mobile PWA",
+ }, context) as { id: string; source: string; result: string; confidence: number };
+ expect(record).toMatchObject({ source: "user-manual", result: "fail", confidence: 1 });
+ const result = await search.run({ project, query: "freezes reconnect", kind: "test" }, context) as {
+ hits: Array<{ record: { id: string; source: string; result: string } }>
+ };
+ expect(result.hits[0].record).toMatchObject({ id: record.id, source: "user-manual", result: "fail" });
+ });
+
+ it("replays a bounded read-only candidate script and promotes it to tested", async () => {
+ const runner = LEARNING_TOOLS.find((tool) => tool.name === "project_script_run")!;
+ const { writeAutomationScript, readAutomationScript } = await import("@/lib/orchestration/repo-memory");
+ const now = new Date().toISOString();
+ const script = {
+ schemaVersion: 1 as const, id: "script-test-health", recipeId: "recipe-test-health",
+ status: "candidate" as const, intent: "verify system health", project,
+ steps: [{ tool: "sys_stats" }], output: { format: "structured-json" as const },
+ gates: {
+ repeatedPattern: true, stableSteps: true, clearInputs: true, clearOutputs: true,
+ sideEffectsUnderstood: true, secretSafe: true, tested: false,
+ },
+ createdAt: now, updatedAt: now,
+ };
+ await writeAutomationScript(project, script, script.id, true);
+ const result = await runner.run({ project, script_id: script.id }, { actor: "mcp:script", scope: "write" }) as {
+ status: string; success: boolean; stepsExecuted: number; outputs: Array<{ tool: string; state: string }>; manifestPath?: string;
+ };
+ expect(result).toMatchObject({ status: "tested", success: true, stepsExecuted: 1 });
+ expect(result.outputs).toEqual([expect.objectContaining({ tool: "sys_stats", state: "completed" })]);
+ expect(result.manifestPath).toBe(`.agent/scripts/${script.id}.json`);
+ await expect(readAutomationScript(project, script.id)).resolves.toMatchObject({ status: "tested", gates: { tested: true } });
+ await expect(fs.lstat(path.join(project, `.agent/scripts/${script.id}.candidate.json`))).rejects.toMatchObject({ code: "ENOENT" });
+ });
+
+ it("refuses a tampered automation manifest that attempts a write or exec tool", async () => {
+ const runner = LEARNING_TOOLS.find((tool) => tool.name === "project_script_run")!;
+ const { writeAutomationScript } = await import("@/lib/orchestration/repo-memory");
+ const now = new Date().toISOString();
+ const script = {
+ schemaVersion: 1 as const, id: "script-tampered", recipeId: "recipe-tampered",
+ status: "candidate" as const, intent: "unsafe replay", project,
+ steps: [{ tool: "exec_run", args: { command: "echo no" } }], output: { format: "structured-json" as const },
+ gates: { repeatedPattern: true, stableSteps: true, clearInputs: true, clearOutputs: true, sideEffectsUnderstood: true, secretSafe: true, tested: false },
+ createdAt: now, updatedAt: now,
+ };
+ await writeAutomationScript(project, script, script.id, true);
+ await expect(runner.run({ project, script_id: script.id }, { actor: "mcp:script", scope: "write" })).rejects.toThrow(/not replay-safe/i);
+ });
+
+ it("keeps a trivial low-risk success memory-light and does not create .agent", async () => {
+ const lightProject = path.join(dir, `light-${Date.now()}`);
+ await fs.mkdir(lightProject);
+ await fs.writeFile(path.join(lightProject, "package.json"), JSON.stringify({ name: "light-fixture" }));
+ const start = LEARNING_TOOLS.find((tool) => tool.name === "workflow_start")!;
+ const finish = LEARNING_TOOLS.find((tool) => tool.name === "workflow_finish")!;
+ const context = { actor: "mcp:rasmic-light", scope: "write" as const };
+ const started = await start.run({ intent: "fix a typo in docs only", project: lightProject }, context) as {
+ workflow: { id: string; orchestration?: { risk: string; memoryRelevance: string } };
+ };
+ expect(started.workflow.orchestration).toMatchObject({ risk: "low", memoryRelevance: "low" });
+ const done = await finish.run({
+ workflow_id: started.workflow.id, summary: "typo fixed and targeted check passed", success: true,
+ }, context) as { evidence: { path?: string }; repoMemory: { taskMemoryId?: string } };
+ expect(done.evidence.path).toBeUndefined();
+ expect(done.repoMemory.taskMemoryId).toBeUndefined();
+ await expect(fs.lstat(path.join(lightProject, ".agent"))).rejects.toMatchObject({ code: "ENOENT" });
+ });
+
});
diff --git a/lib/mcp/tools-learning.ts b/lib/mcp/tools-learning.ts
index 6031b33d..58358afb 100644
--- a/lib/mcp/tools-learning.ts
+++ b/lib/mcp/tools-learning.ts
@@ -1,11 +1,45 @@
import { inspectProject, resolveProjectHint } from "@/lib/host";
-import { activeWorkflowForActor, cancelWorkflow, finishWorkflow, markRecipeUsed, startWorkflow } from "@/lib/skills/memory";
+import { activeWorkflowForActor, cancelWorkflow, finishWorkflow, markRecipeUsed, startWorkflow, summarizeProjectContention } from "@/lib/skills/memory";
import { searchSkillMemory } from "@/lib/skills/search";
+import { assessAutomationPromotion, buildAutomationScriptManifest, isReplaySafeTool, progressiveVerification } from "@/lib/orchestration/automation";
+import { classifyTask, gitChangedPaths } from "@/lib/orchestration/classifier";
+import { buildEvidenceReceipt, validateEvidenceReceipt } from "@/lib/orchestration/evidence";
+import { ingestManualUserTest, readAutomationScript, searchRepoMemory, upsertRepoMemory, writeAutomationScript, writeEvidenceReceipt, writePortableRecipe } from "@/lib/orchestration/repo-memory";
+import type { EvidenceInput, RepoMemoryKind, RepoMemoryLifecycle, RepoMemoryResult, RepoMemorySource, WorkflowOrchestrationSnapshot } from "@/lib/orchestration/types";
import { allows } from "./scope";
import { type McpTool, str, opt, S } from "./tool-kit";
import { toolsetInfo } from "./toolset";
import { WORKFLOW_PROGRESS_URI } from "./ui-resources";
+function optionalStringList(value: unknown, max = 40): string[] {
+ return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && Boolean(item.trim())).slice(0, max) : [];
+}
+
+function evidenceInput(value: unknown): EvidenceInput | undefined {
+ if (!value || typeof value !== "object") return undefined;
+ const row = value as Record<string, unknown>;
+ const out: EvidenceInput = {
+ ...(typeof row.environment === "string" && row.environment ? { environment: row.environment } : {}),
+ claims: optionalStringList(row.claims), tests: optionalStringList(row.tests), build: optionalStringList(row.build),
+ deployment: optionalStringList(row.deployment), health: optionalStringList(row.health), artifacts: optionalStringList(row.artifacts),
+ manualVerification: optionalStringList(row.manual_verification), knownRisks: optionalStringList(row.known_risks),
+ };
+ return out;
+}
+
+function evidenceSchema() {
+ const list = { type: "array", maxItems: 40, items: { type: "string" } };
+ return {
+ type: "object",
+ description: "Structured verification evidence. Required for success on new HIGH-risk workflows.",
+ properties: {
+ environment: { type: "string" }, claims: list, tests: list, build: list, deployment: list, health: list, artifacts: list,
+ manual_verification: list, known_risks: list,
+ },
+ additionalProperties: false,
+ };
+}
+
const visibleTools = async (scope: "read" | "write" | "exec"): Promise<McpTool[]> => {
const { TOOLS } = await import("./tools");
return TOOLS.filter((tool) => allows(scope, tool.scope));
@@ -121,6 +155,8 @@ export const LEARNING_TOOLS: McpTool[] = [
intent: { type: "string", description: "The user's task in one complete sentence." },
project: { type: "string", description: "Optional project id from projects_list, absolute path, name or alias (e.g. os-vps, mso, projects/mso)." },
constraints: { type: "string", description: "Optional important constraints, such as no downtime or WebP only." },
+ affected_paths: { type: "array", maxItems: 80, items: { type: "string" }, description: "Optional expected files/directories this workflow may touch; used for pre-merge collision detection." },
+ reserved_resources: { type: "array", maxItems: 40, items: { type: "string" }, description: "Optional shared resources such as port:4173, database:development, deployment:staging, queue:name." },
}, ["intent"]),
run: async (a, context) => {
const actor = context.workflowActor ?? context.actor;
@@ -143,6 +179,42 @@ export const LEARNING_TOOLS: McpTool[] = [
const repository = project
? await inspectProject(project, { includeGitStatus: context.scope === "exec" }).catch(() => undefined)
: undefined;
+ const changedPaths = gitChangedPaths(repository?.git.changes ?? []);
+ const affectedPaths = optionalStringList(a.affected_paths, 80);
+ const reservedResources = optionalStringList(a.reserved_resources, 40);
+ const contention = project
+ ? await summarizeProjectContention(project.path, affectedPaths, reservedResources)
+ : { activeWorkflowCount: 0, conflictingWorkflowCount: 0, overlappingPaths: [], overlappingResources: [] };
+ const activeProjectWorkflows = contention.activeWorkflowCount;
+ const classification = classifyTask({
+ intent, constraints: opt(a, "constraints"), scope: context.scope, changedPaths, activeProjectWorkflows,
+ collisionPaths: contention.overlappingPaths, collisionResources: contention.overlappingResources,
+ });
+ const repoMemory = project && classification.memoryRelevance !== "low"
+ ? await searchRepoMemory(project.path, { query: intent, limit: 7 }).catch(() => [])
+ : [];
+ const reusableScript = project && search.recommendedRecipe
+ ? await readAutomationScript(project.path, `script_${search.recommendedRecipe.id}`).catch(() => null)
+ : null;
+ const contextEstimateTokens = Math.ceil([
+ intent,
+ ...repoMemory.map((hit) => `${hit.record.title} ${hit.record.summary}`),
+ search.recommendedRecipe?.description ?? "",
+ ].join("\n").length / 4);
+ const orchestration: WorkflowOrchestrationSnapshot = {
+ ...classification,
+ ...(repository?.git.head?.sha ? { baseCommit: repository.git.head.sha } : {}),
+ ...(repository?.git.branch ? { baseBranch: repository.git.branch } : {}),
+ ...(project?.path ? { workspacePath: project.path } : {}),
+ changedPaths, affectedPaths, reservedResources,
+ overlappingPaths: contention.overlappingPaths, overlappingResources: contention.overlappingResources,
+ activeProjectWorkflows, conflictingWorkflowCount: contention.conflictingWorkflowCount,
+ memoryHits: repoMemory.length + (search.recommendedRecipe ? 1 : 0),
+ contextEstimateTokens,
+ cleanupState: classification.isolation === "direct" ? "not-required" : "pending",
+ ...(search.recommendedRecipe ? { recipeUsed: search.recommendedRecipe.id } : {}),
+ createdAt: new Date().toISOString(),
+ };
const toolset = toolsetInfo(tools, context.scope);
// Discovery incompleteness travels WITH the bootstrap. A model told "here is the
// project and the trusted skills" will not re-check whether the scan covered the
@@ -157,6 +229,7 @@ export const LEARNING_TOOLS: McpTool[] = [
intent,
project: project?.path ?? projectHint,
constraints: opt(a, "constraints"),
+ orchestration,
});
// Recommendation telemetry is useful, but failure to persist lastUsedAt must
// never turn a successfully-created workflow into an opaque tool failure.
@@ -171,21 +244,45 @@ export const LEARNING_TOOLS: McpTool[] = [
project: project ?? (projectHint ? { hint: projectHint, matchedBy: "unresolved" } : undefined),
repository,
discovery,
+ orchestration: {
+ classification,
+ verificationPlan: progressiveVerification(classification.risk),
+ automation: reusableScript ? {
+ scriptId: reusableScript.id, status: reusableScript.status,
+ instruction: reusableScript.status === "tested"
+ ? "Prefer project_script_run before replanning this deterministic repeated route."
+ : "Run project_script_run once to verify this bounded candidate; success promotes it to tested.",
+ } : undefined,
+ memory: repoMemory.map((hit) => ({
+ id: hit.record.id, kind: hit.record.kind, title: hit.record.title, summary: hit.record.summary,
+ status: hit.record.status, score: hit.score, lastVerified: hit.record.lastVerified,
+ })),
+ },
trace: [
`[MSO] connected · ${context.scope} scope · ${toolset.toolCount} tools · ${toolset.version}/${toolset.hash}`,
project ? `[Project] ${project.hint} → ${project.path} (${project.matchedBy})` : `[Project] ${projectHint ?? "not specified"}`,
+ `[Risk] ${classification.risk} · ${classification.complexity} complexity · ${classification.contention} contention · ${classification.isolation}`,
+ `[Memory] ${repoMemory.length} repo-local hit(s) · ${search.recommendedRecipe ? "recipe available" : "no verified recipe selected"} · ~${contextEstimateTokens} context tokens`,
+ ...(reusableScript ? [`[Automation] ${reusableScript.status} script ${reusableScript.id} available`] : []),
+ ...(contention.conflictingWorkflowCount ? [`[Collision] ${contention.conflictingWorkflowCount} workflow(s) overlap declared paths/resources`] : []),
...(discovery.complete ? [] : [`[Discovery] partial scan — ${search.catalog.truncationReasons.join(", ")}; do not conclude something is absent`]),
- "[Plan] inspect → change → test/build when needed → verify → workflow_finish",
+ "[Plan] classify → retrieve minimal memory → isolate if required → execute → progressive verify → learn → workflow_finish",
],
policy: {
- simple: "Use bounded tools for one or two direct operations.",
+ simple: "LOW-risk work may run directly with a targeted check; branch/worktree is a safety tool, not a goal.",
+ isolation: classification.risk === "high"
+ ? "HIGH-risk work requires isolation plus explicit verification before integration."
+ : classification.isolation === "optional-worktree"
+ ? "Use a short-lived branch/worktree when it reduces current contention."
+ : "Direct work is acceptable when scope remains isolated.",
repository: "For short repository-wide search/git checks use one narrow exec_run batch; for tests/builds that may exceed 30 seconds use exec_job_start and poll exec_job_status.",
progress: "Show only high-level feature/tool badges and outcomes; never private chain-of-thought.",
- finish: "Call workflow_finish with this exact workflow id only after independent verification; use workflow_cancel for an abandoned run.",
+ manualUserTest: "When the user reports a manual test result, persist it with project_memory_upsert source=user-manual; a failed manual test outranks an automated healthy assumption.",
+ finish: "Call workflow_finish with this exact workflow id only after independent verification; new HIGH-risk workflows require structured evidence. Use workflow_cancel for an abandoned run.",
},
},
search,
- instruction: "Use the returned project, trusted skill, and safe recipe directly. Verify the result, then call workflow_finish.",
+ instruction: "Use the smallest useful returned memory context and any safe recipe. Follow the risk/isolation policy, verify progressively, then call workflow_finish with evidence.",
};
},
},
@@ -236,7 +333,7 @@ export const LEARNING_TOOLS: McpTool[] = [
name: "workflow_finish",
description:
"Finish one exact learned workflow after verification. workflow_id is required so another conversation using the same token cannot close the wrong run. " +
- "MSO saves the redacted sequence and keeps the fastest successful path. Never put credentials or raw file contents in summary.",
+ "MSO saves a redacted Evidence Receipt, task/failure memory, recipe quality, and safe automation-promotion metadata. New HIGH-risk workflows cannot claim success without explicit evidence.",
scope: "write",
annotations: { idempotentHint: false },
limit: { key: "workflow.memory", max: 30, windowMs: 60_000 },
@@ -245,13 +342,237 @@ export const LEARNING_TOOLS: McpTool[] = [
workflow_id: { type: "string", description: "Exact id returned by workflow_start." },
summary: { type: "string", description: "Concise outcome and verification result; no secrets." },
success: { type: "boolean", description: "True only after the requested result is verified." },
+ evidence: evidenceSchema(),
}, ["workflow_id", "summary", "success"]),
- run: (a, context) => finishWorkflow({
- actor: context.workflowActor ?? context.actor,
- recipeActor: context.recipeActor ?? context.actor,
- workflowId: str(a, "workflow_id"),
- summary: str(a, "summary"),
- success: a.success === true,
- }),
+ run: async (a, context) => {
+ const actor = context.workflowActor ?? context.actor;
+ const workflowId = str(a, "workflow_id");
+ const summary = str(a, "summary");
+ const success = a.success === true;
+ const workflow = await activeWorkflowForActor(actor, workflowId);
+ if (!workflow) throw new Error("workflow_id was not found for this MSO session");
+ const project = workflow.project ? await resolveProjectHint(workflow.project).catch(() => null) : null;
+ const finalRepository = project
+ ? await inspectProject(project, { includeGitStatus: context.scope === "exec" }).catch(() => undefined)
+ : undefined;
+ const risk = workflow.orchestration?.risk ?? classifyTask({
+ intent: workflow.intent, constraints: workflow.constraints, scope: context.scope,
+ }).risk;
+ const suppliedEvidence = evidenceInput(a.evidence);
+ const receipt = buildEvidenceReceipt({
+ workflow, summary, success, evidence: suppliedEvidence,
+ finalCommit: finalRepository?.git.head?.sha,
+ });
+ const validation = validateEvidenceReceipt(receipt, { success, risk });
+ // Backward compatibility: only workflows created with RASMIC metadata get the new
+ // hard gate. Legacy in-flight workflows can still close under their old contract.
+ if (workflow.orchestration && !validation.valid) throw new Error(validation.errors.join("; "));
+
+ const finished = await finishWorkflow({
+ actor, recipeActor: context.recipeActor ?? context.actor, workflowId, summary, success,
+ });
+ const automation = assessAutomationPromotion(finished.recipe);
+ const persistenceWarnings: string[] = [];
+ let evidencePath: string | undefined;
+ let taskMemoryId: string | undefined;
+ let scriptPath: string | undefined;
+ const explicitEvidence = Boolean(suppliedEvidence && [
+ suppliedEvidence.tests, suppliedEvidence.build, suppliedEvidence.deployment,
+ suppliedEvidence.health, suppliedEvidence.artifacts, suppliedEvidence.manualVerification,
+ suppliedEvidence.knownRisks,
+ ].some((items) => Array.isArray(items) && items.length > 0));
+ const shouldPersistEvidence = risk !== "low" || !success || explicitEvidence;
+ const shouldPersistTaskMemory = shouldPersistEvidence || workflow.orchestration?.memoryRelevance !== "low";
+ const memoryScope = [...new Set([
+ ...(workflow.orchestration?.affectedPaths ?? []),
+ ...(workflow.orchestration?.changedPaths ?? []),
+ ])];
+
+ if (project) {
+ try {
+ if (shouldPersistEvidence) evidencePath = await writeEvidenceReceipt(project.path, receipt);
+ if (shouldPersistTaskMemory) {
+ const taskMemory = await upsertRepoMemory(project.path, {
+ kind: "task",
+ title: `${success ? "Completed" : "Failed"}: ${workflow.intent.slice(0, 120)}`,
+ summary,
+ source: "system",
+ result: success ? "pass" : "fail",
+ status: success ? "confirmed" : "active",
+ confidence: success ? 0.9 : 1,
+ importance: risk === "high" ? 0.9 : risk === "medium" ? 0.7 : 0.5,
+ lastVerified: success ? receipt.createdAt : undefined,
+ scope: memoryScope,
+ tags: ["workflow", risk, workflow.orchestration?.complexity ?? "unknown"],
+ commit: receipt.finalCommit,
+ environment: receipt.environment,
+ happened: summary,
+ ...(success ? { worked: summary } : { failed: summary }),
+ learned: success ? "Result is backed by the attached Evidence Receipt." : "Do not treat this workflow as healthy until the failure is resolved and re-verified.",
+ reuse: automation.stage === "verified" ? "A verified reusable recipe exists for similar work; prefer it before replanning from scratch." : "Retrieve this task memory when similar scope is attempted again.",
+ });
+ taskMemoryId = taskMemory.id;
+ }
+ if (!success) {
+ await upsertRepoMemory(project.path, {
+ kind: "failure", title: `Workflow failure: ${workflow.intent.slice(0, 120)}`, summary, source: "system",
+ result: "fail", status: "active", confidence: 1, importance: 0.9,
+ scope: memoryScope, tags: ["workflow-failure", risk], commit: receipt.finalCommit,
+ failed: summary, reuse: "Check this failure before repeating the same approach.",
+ });
+ }
+ if (automation.stage !== "observed") {
+ await writePortableRecipe(project.path, {
+ schemaVersion: 1, id: finished.recipe.id, intent: finished.recipe.intent, summary: finished.recipe.summary,
+ stage: automation.stage, attempts: finished.recipe.attempts, successes: finished.recipe.successes, failures: finished.recipe.failures,
+ successRate: automation.successRate, bestSteps: finished.recipe.bestSteps, quality: finished.recipe.quality, updatedAt: finished.recipe.updatedAt,
+ }, finished.recipe.id);
+ }
+ if (automation.scriptCandidate) {
+ const script = buildAutomationScriptManifest(finished.recipe, { tested: false });
+ scriptPath = await writeAutomationScript(project.path, script, script.id, true);
+ }
+ } catch (error) {
+ persistenceWarnings.push(error instanceof Error ? error.message : String(error));
+ }
+ }
+
+ return {
+ ...finished,
+ evidence: { receipt, valid: validation.valid, errors: validation.errors, path: evidencePath },
+ automation,
+ metrics: {
+ toolCalls: workflow.steps.length,
+ executionDurationMs: finished.currentDurationMs,
+ retries: finished.recipe.lastQuality?.retries ?? 0,
+ memoryHits: workflow.orchestration?.memoryHits ?? 0,
+ contextEstimateTokens: workflow.orchestration?.contextEstimateTokens ?? 0,
+ recipeUsed: Boolean(workflow.orchestration?.recipeUsed),
+ recipeStage: automation.stage,
+ scriptCandidateCreated: Boolean(scriptPath),
+ },
+ repoMemory: { taskMemoryId, scriptPath, warnings: persistenceWarnings },
+ };
+ },
+ },
+ {
+ name: "project_memory_search",
+ description:
+ "Search compact repo-local .agent memory for the smallest useful context. Ranks confirmed/current memory above stale or superseded history and never reads raw chat transcripts.",
+ scope: "read",
+ annotations: { readOnlyHint: true, idempotentHint: true },
+ limit: { key: "project.memory.search", max: 60, windowMs: 60_000 },
+ inputSchema: S({
+ project: { type: "string", description: "Validated project id, path, name or alias." },
+ query: { type: "string", description: "What prior task/debug/test/decision/failure context is relevant." },
+ kind: { type: "string", enum: ["task", "debug", "test", "decision", "failure"] },
+ limit: { type: "number", minimum: 1, maximum: 20 },
+ include_history: { type: "boolean", description: "Include superseded/archived records. Default false." },
+ }, ["project"]),
+ run: async (a) => {
+ const project = await resolveProjectHint(str(a, "project"));
+ if (!project) throw new Error(`project not found: ${String(a.project)}`);
+ const kind = typeof a.kind === "string" ? a.kind as RepoMemoryKind : undefined;
+ return {
+ project: project.path,
+ hits: await searchRepoMemory(project.path, {
+ query: opt(a, "query"), kinds: kind ? [kind] : undefined,
+ limit: typeof a.limit === "number" ? a.limit : undefined, includeHistory: a.include_history === true,
+ }),
+ };
+ },
+ },
+ {
+ name: "project_memory_upsert",
+ description:
+ "Create or update one compact repo-local task/debug/test/decision/failure memory. Use source=user-manual for the user's own test result so manual evidence can override an automated healthy assumption. Secrets are redacted before persistence.",
+ scope: "write",
+ annotations: { idempotentHint: false },
+ limit: { key: "project.memory.write", max: 60, windowMs: 60_000 },
+ audit: { action: "fs.write" as const, targetArg: "project" },
+ inputSchema: S({
+ project: { type: "string" }, id: { type: "string", description: "Existing memory id to update." },
+ kind: { type: "string", enum: ["task", "debug", "test", "decision", "failure"] },
+ title: { type: "string" }, summary: { type: "string" }, observation: { type: "string" },
+ source: { type: "string", enum: ["agent", "system", "user-manual", "automation"] },
+ result: { type: "string", enum: ["pass", "fail", "unknown"] },
+ status: { type: "string", enum: ["active", "confirmed", "superseded", "archived"] },
+ environment: { type: "string" }, commit: { type: "string" },
+ confidence: { type: "number", minimum: 0, maximum: 1 }, importance: { type: "number", minimum: 0, maximum: 1 },
+ scope: { type: "array", items: { type: "string" }, maxItems: 40 },
+ tags: { type: "array", items: { type: "string" }, maxItems: 40 },
+ supersedes: { type: "array", items: { type: "string" }, maxItems: 40 },
+ }, ["project", "kind", "title", "summary"]),
+ run: async (a) => {
+ const project = await resolveProjectHint(str(a, "project"));
+ if (!project) throw new Error(`project not found: ${String(a.project)}`);
+ const kind = str(a, "kind") as RepoMemoryKind;
+ const source = (opt(a, "source") ?? "agent") as RepoMemorySource;
+ const result = opt(a, "result") as RepoMemoryResult | undefined;
+ if (kind === "test" && source === "user-manual" && (result === "pass" || result === "fail") && !opt(a, "id")) {
+ return ingestManualUserTest(project.path, {
+ observation: opt(a, "observation") ?? str(a, "summary"), result, title: str(a, "title"),
+ environment: opt(a, "environment"), scope: optionalStringList(a.scope), tags: optionalStringList(a.tags), commit: opt(a, "commit"),
+ });
+ }
+ return upsertRepoMemory(project.path, {
+ id: opt(a, "id"), kind, title: str(a, "title"), summary: str(a, "summary"), observation: opt(a, "observation"),
+ source, result, status: opt(a, "status") as RepoMemoryLifecycle | undefined, environment: opt(a, "environment"), commit: opt(a, "commit"),
+ confidence: typeof a.confidence === "number" ? a.confidence : undefined, importance: typeof a.importance === "number" ? a.importance : undefined,
+ scope: optionalStringList(a.scope), tags: optionalStringList(a.tags), supersedes: optionalStringList(a.supersedes),
+ });
+ },
+ },
+ {
+ name: "project_script_run",
+ description:
+ "Execute one repo-local RASMIC automation script produced from a repeated stable recipe. Runtime re-validates every step and permits bounded read-only tools only; write/exec steps are refused even if a manifest was tampered. A successful candidate replay is promoted to tested.",
+ scope: "write",
+ annotations: { idempotentHint: false },
+ limit: { key: "project.script.run", max: 30, windowMs: 60_000 },
+ audit: { action: "fs.write" as const, targetArg: "project" },
+ inputSchema: S({
+ project: { type: "string", description: "Validated project id, path, name or alias that owns .agent/scripts." },
+ script_id: { type: "string", description: "Exact script id returned by workflow_start automation metadata or workflow_finish." },
+ }, ["project", "script_id"]),
+ run: async (a, context) => {
+ const project = await resolveProjectHint(str(a, "project"));
+ if (!project) throw new Error(`project not found: ${String(a.project)}`);
+ const scriptId = str(a, "script_id");
+ const script = await readAutomationScript(project.path, scriptId);
+ if (!script) throw new Error("automation script not found");
+ if (script.steps.length > 12) throw new Error("automation script exceeds the 12-step replay bound");
+ const { TOOLS_BY_NAME } = await import("./tools");
+ const outputs: Array<{ tool: string; state: "completed"; result: string }> = [];
+ const startedAt = Date.now();
+ for (const step of script.steps) {
+ if (!isReplaySafeTool(step.tool)) throw new Error(`automation step ${step.tool} is not replay-safe`);
+ const tool = TOOLS_BY_NAME.get(step.tool);
+ if (!tool || tool.scope !== "read") throw new Error(`automation step ${step.tool} is unavailable or not read-only`);
+ const args = { ...(step.args ?? {}) };
+ for (const required of tool.inputSchema.required ?? []) {
+ if (args[required] == null) throw new Error(`automation step ${step.tool} is missing required input ${required}`);
+ }
+ const result = await tool.run(args, context);
+ let compact: string;
+ try { compact = JSON.stringify(result); } catch { compact = String(result); }
+ if (compact.length > 1800) compact = `${compact.slice(0, 1800)}…`;
+ outputs.push({ tool: step.tool, state: "completed", result: compact });
+ }
+ let status = script.status;
+ let manifestPath: string | undefined;
+ if (script.status === "candidate") {
+ const tested = {
+ ...script, status: "tested" as const, updatedAt: new Date().toISOString(),
+ gates: { ...script.gates, tested: true },
+ };
+ manifestPath = await writeAutomationScript(project.path, tested, tested.id, false);
+ status = "tested";
+ }
+ return {
+ scriptId, status, success: true, stepsExecuted: outputs.length,
+ durationMs: Date.now() - startedAt, manifestPath, outputs,
+ };
+ },
},
];
diff --git a/lib/orchestration/automation.ts b/lib/orchestration/automation.ts
new file mode 100644
index 00000000..a3d6e276
--- /dev/null
+++ b/lib/orchestration/automation.ts
@@ -0,0 +1,112 @@
+import type { LearnedRecipe, WorkflowStep } from "@/lib/skills/memory";
+import type { AutomationAssessment, AutomationScriptManifest } from "./types";
+
+export const REPLAY_SAFE_TOOLS = new Set([
+ "fs_list", "fs_read", "fs_search", "fs_usage", "sys_stats", "sys_processes",
+ "apps_list", "apps_logs", "projects_list", "project_capabilities", "skills_list",
+ "skills_read", "browser_status", "infra_providers_list",
+ "dokploy_projects_list", "cloudflare_zones_list",
+]);
+
+function successfulTools(steps: WorkflowStep[]): string[] {
+ return steps.filter((step) => step.state === "completed").map((step) => step.tool);
+}
+
+function similarRoute(recipe: LearnedRecipe): boolean {
+ const best = successfulTools(recipe.bestSteps);
+ const last = successfulTools(recipe.lastSteps);
+ if (!best.length || !last.length) return false;
+ const compactLast = last.filter((tool, index) => index === 0 || tool !== last[index - 1]);
+ const compactBest = best.filter((tool, index) => index === 0 || tool !== best[index - 1]);
+ if (compactBest.length !== compactLast.length) return false;
+ return compactBest.every((tool, index) => tool === compactLast[index]);
+}
+
+export function isReplaySafeTool(tool: string): boolean { return REPLAY_SAFE_TOOLS.has(tool); }
+
+function replayable(step: WorkflowStep): boolean {
+ if (!isReplaySafeTool(step.tool)) return false;
+ if (["sys_stats", "sys_processes", "apps_list", "browser_status", "infra_providers_list", "dokploy_projects_list", "cloudflare_zones_list"].includes(step.tool)) return true;
+ return Boolean(step.args && Object.keys(step.args).length > 0) || Boolean(step.target);
+}
+
+export function assessAutomationPromotion(recipe: LearnedRecipe): AutomationAssessment {
+ const attempts = Math.max(0, recipe.attempts || 0);
+ const successes = Math.max(0, recipe.successes || 0);
+ const failures = Math.max(0, recipe.failures || 0);
+ const successRate = attempts ? successes / attempts : 0;
+ const stableSteps = attempts >= 2 && similarRoute(recipe);
+ let stage: AutomationAssessment["stage"] = "observed";
+ const reasons: string[] = [];
+
+ if (successes >= 2 && attempts >= 2) stage = "candidate";
+ if (successes >= 3 && successRate >= 0.8 && stableSteps) stage = "verified";
+
+ if (attempts < 2) reasons.push("needs repeated observations");
+ if (successes < 2) reasons.push("needs at least two successful runs for a recipe candidate");
+ if (!stableSteps) reasons.push("tool route is not stable across successful runs yet");
+ if (failures > 0 && successRate < 0.8) reasons.push("success rate is below the verification gate");
+
+ const replaySafe = recipe.bestSteps.length > 0 && recipe.bestSteps.length <= 12 && recipe.bestSteps.every(replayable);
+ if (recipe.bestSteps.length > 12) reasons.push("route is too long for bounded script replay; keep it as a recipe");
+ else if (!replaySafe) reasons.push("route contains contextual or non-replay-safe steps; keep it as a recipe");
+ const scriptCandidate = stage === "verified" && replaySafe;
+
+ return {
+ stage,
+ successRate: Math.round(successRate * 1000) / 1000,
+ stableSteps,
+ scriptCandidate,
+ reasons: [...new Set(reasons)].slice(0, 10),
+ };
+}
+
+export function buildAutomationScriptManifest(recipe: LearnedRecipe, options: { tested?: boolean } = {}): AutomationScriptManifest {
+ const assessment = assessAutomationPromotion(recipe);
+ if (!assessment.scriptCandidate) throw new Error("recipe has not passed script promotion gates");
+ const now = new Date().toISOString();
+ return {
+ schemaVersion: 1,
+ id: `script_${recipe.id}`,
+ recipeId: recipe.id,
+ status: options.tested ? "tested" : "candidate",
+ intent: recipe.intent,
+ ...(recipe.project ? { project: recipe.project } : {}),
+ steps: recipe.bestSteps.map((step) => ({ tool: step.tool, ...(step.args ? { args: step.args } : {}) })),
+ output: { format: "structured-json" },
+ gates: {
+ repeatedPattern: recipe.attempts >= 2,
+ stableSteps: assessment.stableSteps,
+ clearInputs: true,
+ clearOutputs: true,
+ sideEffectsUnderstood: true,
+ secretSafe: true,
+ tested: options.tested === true,
+ },
+ createdAt: recipe.createdAt || now,
+ updatedAt: now,
+ };
+}
+
+export type ReviewLoopState = {
+ iteration: number;
+ maxIterations: number;
+ actionableFindings: number;
+ repeatedNoProgress?: boolean;
+ newRegressions?: boolean;
+ destructiveUncertainty?: boolean;
+ humanDecisionRequired?: boolean;
+};
+
+export function reviewLoopDecision(state: ReviewLoopState): "fix" | "verify" | "stop" {
+ if (state.iteration >= state.maxIterations) return "stop";
+ if (state.repeatedNoProgress || state.newRegressions || state.destructiveUncertainty || state.humanDecisionRequired) return "stop";
+ if (state.actionableFindings > 0) return "fix";
+ return "verify";
+}
+
+export function progressiveVerification(risk: "low" | "medium" | "high"): string[] {
+ if (risk === "low") return ["targeted check"];
+ if (risk === "medium") return ["targeted check", "affected tests", "build if affected"];
+ return ["targeted check", "affected tests", "build", "broader regression", "E2E/release verification when applicable"];
+}
diff --git a/lib/orchestration/classifier.test.ts b/lib/orchestration/classifier.test.ts
new file mode 100644
index 00000000..27103898
--- /dev/null
+++ b/lib/orchestration/classifier.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { classifyTask, gitChangedPaths, sharedResourceWarnings } from "./classifier";
+
+describe("RASMIC risk and contention classifier", () => {
+ it("keeps trivial docs work direct without a worktree", () => {
+ const result = classifyTask({ intent: "fix a typo in docs only", scope: "write" });
+ expect(result).toMatchObject({
+ risk: "low",
+ complexity: "light",
+ isolation: "direct",
+ verification: "targeted",
+ });
+ });
+
+ it("marks contained feature work medium with optional isolation", () => {
+ const result = classifyTask({ intent: "implement one contained feature across a few files", scope: "write" });
+ expect(result).toMatchObject({ risk: "medium", isolation: "optional-worktree", verification: "affected" });
+ });
+
+ it("requires isolated work for high-risk auth/schema/infra work", () => {
+ const result = classifyTask({
+ intent: "refactor authentication and database schema before production deployment",
+ scope: "exec",
+ });
+ expect(result).toMatchObject({ risk: "high", complexity: "heavy", isolation: "isolated-worktree", verification: "full" });
+ });
+
+ it("raises contention before a merge conflict when another workflow and shared files exist", () => {
+ const result = classifyTask({
+ intent: "upgrade dependencies for the release",
+ scope: "exec",
+ changedPaths: ["package.json", "src/auth/index.ts"],
+ activeProjectWorkflows: 1,
+ });
+ expect(result.contention).toBe("high");
+ expect(result.sharedResourceWarnings.join(" ")).toMatch(/package|deployment/);
+ });
+
+ it("extracts changed paths and shared resources from git status lines", () => {
+ expect(gitChangedPaths([" M package.json", "R src/a.ts -> src/b.ts", "?? docs/new.md"])).toEqual([
+ "package.json",
+ "src/b.ts",
+ "docs/new.md",
+ ]);
+ expect(sharedResourceWarnings("run docker service on port 4173", [])).toEqual(expect.arrayContaining([
+ expect.stringContaining("port"),
+ expect.stringContaining("container"),
+ ]));
+ });
+});
diff --git a/lib/orchestration/classifier.ts b/lib/orchestration/classifier.ts
new file mode 100644
index 00000000..09d0b509
--- /dev/null
+++ b/lib/orchestration/classifier.ts
@@ -0,0 +1,143 @@
+import type { ContentionLevel, TaskClassification } from "./types";
+
+const HIGH_RISK = [
+ /\bauth(?:entication|orization)?\b/i,
+ /\b(schema|migration|database|db)\b/i,
+ /\b(delete|drop|destroy|destructive|wipe|purge)\b/i,
+ /\b(infra(?:structure)?|dns|deploy(?:ment)?|production|prod)\b|\brelease pipeline\b/i,
+ /\b(secret|credential|token|private key|api key)\b/i,
+ /\bpublic api\b/i,
+ /\bdependency (?:upgrade|update)|upgrade dependencies|lockfile\b/i,
+ /\bbroad refactor|repo[- ]wide refactor|architecture rewrite\b/i,
+ /\bmultiple agents?|parallel agents?|multi[- ]agent\b/i,
+];
+
+const MEDIUM_RISK = [
+ /\bfeature\b/i,
+ /\bvertical slice\b/i,
+ /\bmulti[- ]file\b/i,
+ /\brefactor\b/i,
+ /\bruntime\b/i,
+ /\borchestration\b/i,
+ /\bmemory\b/i,
+ /\bworkflow\b/i,
+];
+
+const LOW_HINTS = [
+ /\bdocs?|documentation\b/i,
+ /\btypo\b/i,
+ /\bcopy\b/i,
+ /\bminor (?:ui|style|css)\b/i,
+ /\bstyle only\b/i,
+];
+
+const MEMORY_HIGH = [
+ /\b(debug|bug|freeze|crash|regression|again|repeated|previous|before|manual test|failed test)\b/i,
+ /\brecipe|script|automation|memory\b/i,
+];
+
+const SHARED_RESOURCE_RULES: Array<[RegExp, string]> = [
+ [/\bpackage\.json\b|\b(?:bun|package|pnpm|yarn)-?lock\b/i, "package manifest/lockfile is shared"],
+ [/\b(schema|migration|database|db)\b/i, "database/schema is shared"],
+ [/\bport\s*[:=]?\s*\d{2,5}\b/i, "network port may be shared"],
+ [/\bdocker|compose|container\b/i, "container/service runtime may be shared"],
+ [/\bdeploy(?:ment)?|production|prod\b/i, "deployment target may be shared"],
+ [/\bcache|queue|worker\b/i, "runtime queue/cache may be shared"],
+];
+
+export function gitChangedPaths(changes: string[] = []): string[] {
+ const out = new Set<string>();
+ for (const line of changes) {
+ const body = line.length > 3 ? line.slice(3).trim() : line.trim();
+ if (!body) continue;
+ const renamed = body.split(" -> ").at(-1)?.trim();
+ if (renamed) out.add(renamed.replace(/^"|"$/g, ""));
+ }
+ return [...out].slice(0, 80);
+}
+
+export function sharedResourceWarnings(intent: string, changedPaths: string[] = []): string[] {
+ const haystack = `${intent}\n${changedPaths.join("\n")}`;
+ const warnings = SHARED_RESOURCE_RULES
+ .filter(([pattern]) => pattern.test(haystack))
+ .map(([, warning]) => warning);
+ if (changedPaths.some((path) => /(^|\/)(package\.json|bun\.lock|package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/i.test(path))) {
+ warnings.push("current working tree changes include a shared dependency file");
+ }
+ return [...new Set(warnings)];
+}
+
+function contentionLevel(activeProjectWorkflows: number, changedPaths: string[], warnings: string[]): ContentionLevel {
+ if (activeProjectWorkflows > 0 && (changedPaths.length > 0 || warnings.length > 0)) return "high";
+ if (activeProjectWorkflows > 0 || changedPaths.length > 0 || warnings.length > 0) return "possible";
+ return "none";
+}
+
+export function classifyTask(input: {
+ intent: string;
+ constraints?: string;
+ scope?: "read" | "write" | "exec";
+ changedPaths?: string[];
+ activeProjectWorkflows?: number;
+ collisionPaths?: string[];
+ collisionResources?: string[];
+}): TaskClassification {
+ const text = `${input.intent}\n${input.constraints ?? ""}`;
+ const changedPaths = input.changedPaths ?? [];
+ const active = Math.max(0, input.activeProjectWorkflows ?? 0);
+ const collisionPaths = input.collisionPaths ?? [];
+ const collisionResources = input.collisionResources ?? [];
+ const warnings = sharedResourceWarnings(text, changedPaths);
+ if (collisionPaths.length) warnings.push(`workflow path overlap: ${collisionPaths.slice(0, 6).join(", ")}`);
+ if (collisionResources.length) warnings.push(`workflow shared-resource overlap: ${collisionResources.slice(0, 6).join(", ")}`);
+ const reasons: string[] = [];
+
+ const highMatches = HIGH_RISK.filter((rule) => rule.test(text)).length;
+ const mediumMatches = MEDIUM_RISK.filter((rule) => rule.test(text)).length;
+ const lowOnly = LOW_HINTS.some((rule) => rule.test(text)) && highMatches === 0 && mediumMatches === 0;
+
+ let risk: TaskClassification["risk"] = "low";
+ if (highMatches > 0) risk = "high";
+ else if (mediumMatches > 0 || (input.scope === "exec" && !lowOnly)) risk = "medium";
+ if (risk === "high") reasons.push("high-risk domain detected");
+ else if (risk === "medium") reasons.push("contained multi-step/runtime change detected");
+ else reasons.push("isolated low-risk task detected");
+
+ let complexity: TaskClassification["complexity"] = "light";
+ const wordCount = text.trim().split(/\s+/).filter(Boolean).length;
+ if (risk === "high" || wordCount > 80 || /\b(multiple|several|across|architecture|system)\b/i.test(text)) complexity = "heavy";
+ else if (risk === "medium" || wordCount > 30) complexity = "medium";
+
+ const contention = collisionPaths.length || collisionResources.length ? "high" : contentionLevel(active, changedPaths, warnings);
+ if (active > 0) reasons.push(`${active} active workflow(s) already target this project`);
+ if (changedPaths.length > 0) reasons.push(`${changedPaths.length} pre-existing changed path(s) detected`);
+ if (collisionPaths.length || collisionResources.length) reasons.push("active workflow scope/resource collision detected");
+ if (warnings.length > 0) reasons.push("shared-resource contention is possible");
+
+ let memoryRelevance: TaskClassification["memoryRelevance"] = "low";
+ if (MEMORY_HIGH.some((rule) => rule.test(text)) || complexity === "heavy") memoryRelevance = "high";
+ else if (complexity === "medium") memoryRelevance = "medium";
+
+ const isolation: TaskClassification["isolation"] = risk === "high"
+ ? "isolated-worktree"
+ : risk === "medium"
+ ? "optional-worktree"
+ : "direct";
+
+ const verification: TaskClassification["verification"] = risk === "high"
+ ? "full"
+ : risk === "medium"
+ ? "affected"
+ : "targeted";
+
+ return {
+ risk,
+ complexity,
+ contention,
+ memoryRelevance,
+ isolation,
+ verification,
+ reasons: [...new Set(reasons)].slice(0, 12),
+ sharedResourceWarnings: warnings.slice(0, 12),
+ };
+}
diff --git a/lib/orchestration/evidence-automation.test.ts b/lib/orchestration/evidence-automation.test.ts
new file mode 100644
index 00000000..f9eba4ec
--- /dev/null
+++ b/lib/orchestration/evidence-automation.test.ts
@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+import type { ActiveWorkflow, LearnedRecipe, WorkflowStep } from "@/lib/skills/memory";
+import { assessAutomationPromotion, buildAutomationScriptManifest, progressiveVerification, reviewLoopDecision } from "./automation";
+import { buildEvidenceReceipt, validateEvidenceReceipt } from "./evidence";
+
+const now = new Date().toISOString();
+const orchestration = {
+ risk: "high" as const,
+ complexity: "heavy" as const,
+ contention: "none" as const,
+ memoryRelevance: "high" as const,
+ isolation: "isolated-worktree" as const,
+ verification: "full" as const,
+ reasons: ["high-risk domain detected"],
+ sharedResourceWarnings: [],
+ changedPaths: ["src/auth.ts"],
+ affectedPaths: ["src/auth.ts"],
+ reservedResources: ["database:development"],
+ overlappingPaths: [],
+ overlappingResources: [],
+ activeProjectWorkflows: 0,
+ conflictingWorkflowCount: 0,
+ memoryHits: 0,
+ contextEstimateTokens: 20,
+ cleanupState: "pending" as const,
+ workspacePath: "/tmp/project",
+ baseCommit: "abc123",
+ createdAt: now,
+};
+const workflow: ActiveWorkflow = {
+ id: "wf-test",
+ actor: "mcp:test",
+ scope: "exec",
+ intent: "update authentication before production deployment",
+ project: "/tmp/project",
+ orchestration,
+ startedAt: now,
+ steps: [],
+};
+
+describe("Evidence Receipt", () => {
+ it("refuses a successful high-risk claim without explicit verification evidence", () => {
+ const receipt = buildEvidenceReceipt({ workflow, summary: "done", success: true });
+ const result = validateEvidenceReceipt(receipt, { success: true, risk: "high" });
+ expect(result.valid).toBe(false);
+ expect(result.errors.join(" ")).toMatch(/requires explicit/i);
+ });
+
+ it("accepts high-risk completion when a concrete test/health/manual proof exists", () => {
+ const receipt = buildEvidenceReceipt({
+ workflow,
+ summary: "deployment verified",
+ success: true,
+ evidence: {
+ claims: ["deployment healthy"],
+ tests: ["auth regression suite passed"],
+ health: ["HTTP health 200"],
+ knownRisks: ["none observed"],
+ },
+ finalCommit: "def456",
+ });
+ expect(validateEvidenceReceipt(receipt, { success: true, risk: "high" })).toEqual({ valid: true, errors: [] });
+ expect(receipt).toMatchObject({ baseCommit: "abc123", finalCommit: "def456" });
+ });
+
+ it("redacts secrets from claims and evidence", () => {
+ const receipt = buildEvidenceReceipt({
+ workflow,
+ summary: "token=super-secret",
+ success: false,
+ evidence: { claims: ["Authorization: Bearer ghp_1234567890abcdef"] },
+ });
+ expect(JSON.stringify(receipt)).not.toContain("super-secret");
+ expect(JSON.stringify(receipt)).not.toContain("1234567890abcdef");
+ });
+});
+
+function step(id: string, tool = "sys_stats"): WorkflowStep {
+ return { id, tool, state: "completed", durationMs: 5, ts: now };
+}
+function recipe(overrides: Partial<LearnedRecipe> = {}): LearnedRecipe {
+ return {
+ id: "recipe-1",
+ actor: "mcp:test",
+ scope: "read",
+ intent: "verify server health",
+ normalizedIntent: "verify server health",
+ summary: "healthy",
+ embeddingVersion: "test",
+ embedding: [],
+ bestSteps: [step("best")],
+ lastSteps: [step("last")],
+ attempts: 3,
+ successes: 3,
+ failures: 0,
+ averageDurationMs: 5,
+ fastestDurationMs: 5,
+ lastDurationMs: 5,
+ averageWallDurationMs: 5,
+ lastWallDurationMs: 5,
+ quality: {
+ stepAttempts: 3, completedSteps: 3, failedSteps: 0, deniedSteps: 0,
+ rateLimitedSteps: 0, invalidArgSteps: 0, retries: 0, rollbackSignals: 0,
+ timedSteps: 3, totalStepDurationMs: 15, averageStepDurationMs: 5,
+ },
+ lastQuality: {
+ stepAttempts: 1, completedSteps: 1, failedSteps: 0, deniedSteps: 0,
+ rateLimitedSteps: 0, invalidArgSteps: 0, retries: 0, rollbackSignals: 0,
+ timedSteps: 1, totalStepDurationMs: 5, averageStepDurationMs: 5,
+ },
+ createdAt: now,
+ updatedAt: now,
+ ...overrides,
+ };
+}
+
+describe("recipe to script promotion", () => {
+ it("does not promote a one-off trace", () => {
+ const result = assessAutomationPromotion(recipe({ attempts: 1, successes: 1 }));
+ expect(result).toMatchObject({ stage: "observed", scriptCandidate: false });
+ });
+
+ it("keeps contextual or mutating routes as recipes even after repetition", () => {
+ const execStep = step("exec", "exec_run");
+ const result = assessAutomationPromotion(recipe({ bestSteps: [execStep], lastSteps: [execStep] }));
+ expect(result.stage).toBe("verified");
+ expect(result.scriptCandidate).toBe(false);
+ expect(result.reasons.join(" ")).toMatch(/keep it as a recipe/i);
+ });
+
+ it("promotes a stable deterministic safe route only after repeated verified success", () => {
+ const source = recipe();
+ const assessment = assessAutomationPromotion(source);
+ expect(assessment).toMatchObject({ stage: "verified", stableSteps: true, scriptCandidate: true, successRate: 1 });
+ const manifest = buildAutomationScriptManifest(source, { tested: true });
+ expect(manifest).toMatchObject({
+ recipeId: source.id,
+ status: "tested",
+ output: { format: "structured-json" },
+ gates: { repeatedPattern: true, stableSteps: true, secretSafe: true, tested: true },
+ });
+ });
+});
+
+describe("review and progressive verification", () => {
+ it("uses cheap checks first and reserves the broadest suite for high risk", () => {
+ expect(progressiveVerification("low")).toEqual(["targeted check"]);
+ expect(progressiveVerification("medium")).toEqual(["targeted check", "affected tests", "build if affected"]);
+ expect(progressiveVerification("high").at(-1)).toMatch(/E2E/i);
+ });
+
+ it("stops review loops on no-progress, regressions, destructive uncertainty, human decision, or iteration cap", () => {
+ expect(reviewLoopDecision({ iteration: 0, maxIterations: 3, actionableFindings: 2 })).toBe("fix");
+ expect(reviewLoopDecision({ iteration: 0, maxIterations: 3, actionableFindings: 0 })).toBe("verify");
+ expect(reviewLoopDecision({ iteration: 1, maxIterations: 3, actionableFindings: 2, repeatedNoProgress: true })).toBe("stop");
+ expect(reviewLoopDecision({ iteration: 3, maxIterations: 3, actionableFindings: 2 })).toBe("stop");
+ });
+});
diff --git a/lib/orchestration/evidence.ts b/lib/orchestration/evidence.ts
new file mode 100644
index 00000000..37291898
--- /dev/null
+++ b/lib/orchestration/evidence.ts
@@ -0,0 +1,57 @@
+import type { ActiveWorkflow } from "@/lib/skills/memory";
+import { redactStrings, redactText } from "./redaction";
+import type { EvidenceInput, EvidenceItem, EvidenceReceipt, RiskLevel } from "./types";
+
+const passed = (values: unknown): EvidenceItem[] => redactStrings(values).map((name) => ({ name, status: "pass" as const }));
+
+export function buildEvidenceReceipt(input: {
+ workflow: ActiveWorkflow;
+ summary: string;
+ success: boolean;
+ evidence?: EvidenceInput;
+ finalCommit?: string;
+ environment?: string;
+}): EvidenceReceipt {
+ const evidence = input.evidence ?? {};
+ const orchestration = input.workflow.orchestration;
+ const claims = redactStrings(evidence.claims);
+ if (!claims.length) claims.push(redactText(input.summary, 1200) || (input.success ? "workflow completed" : "workflow failed"));
+ return {
+ schemaVersion: 1,
+ workflow: input.workflow.id,
+ ...(input.workflow.project ? { repo: redactText(input.workflow.project, 240) } : {}),
+ ...(orchestration?.baseCommit ? { baseCommit: orchestration.baseCommit } : {}),
+ ...(input.finalCommit ? { finalCommit: redactText(input.finalCommit, 80) } : {}),
+ ...((evidence.environment || input.environment)
+ ? { environment: redactText(evidence.environment || input.environment || "", 400) }
+ : {}),
+ claims,
+ tests: passed(evidence.tests),
+ build: passed(evidence.build),
+ deployment: passed(evidence.deployment),
+ health: passed(evidence.health),
+ artifacts: redactStrings(evidence.artifacts),
+ manualVerification: passed(evidence.manualVerification),
+ knownRisks: redactStrings(evidence.knownRisks),
+ createdAt: new Date().toISOString(),
+ };
+}
+
+export function evidencePassCount(receipt: EvidenceReceipt): number {
+ return [receipt.tests, receipt.build, receipt.deployment, receipt.health, receipt.manualVerification]
+ .flat()
+ .filter((item) => item.status === "pass").length;
+}
+
+export function validateEvidenceReceipt(receipt: EvidenceReceipt, options: {
+ success: boolean;
+ risk: RiskLevel;
+}): { valid: boolean; errors: string[] } {
+ const errors: string[] = [];
+ if (!receipt.workflow) errors.push("workflow is required");
+ if (!receipt.claims.length) errors.push("at least one claim is required");
+ if (options.success && options.risk === "high" && evidencePassCount(receipt) < 1) {
+ errors.push("a successful high-risk workflow requires explicit test/build/deployment/health/manual verification evidence");
+ }
+ return { valid: errors.length === 0, errors };
+}
diff --git a/lib/orchestration/redaction.ts b/lib/orchestration/redaction.ts
new file mode 100644
index 00000000..33f22451
--- /dev/null
+++ b/lib/orchestration/redaction.ts
@@ -0,0 +1,31 @@
+const QUERY_SECRET = /([?&](?:token|key|secret|password|code)=)[^&\s]+/gi;
+const KEY_VALUE_SECRET = /\b(password|token|secret|api[_-]?key|authorization)\s*[:=]\s*\S+/gi;
+const PREFIX_SECRET = /\b(?:bearer\s+)?(?:sk|pk|ghp|github_pat|mso_mcp)_[a-z0-9_-]{8,}\b/gi;
+const PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+
+export function redactText(value: string, max = 4000): string {
+ let out = value
+ .replace(QUERY_SECRET, "$1[redacted]")
+ .replace(KEY_VALUE_SECRET, "$1=[redacted]")
+ .replace(PREFIX_SECRET, "[redacted]")
+ .replace(PRIVATE_KEY, "[redacted-private-key]")
+ .trim();
+ return out.length > max ? `${out.slice(0, max)}…` : out;
+}
+
+export function redactStrings(values: unknown, maxItems = 40, maxLength = 800): string[] {
+ if (!Array.isArray(values)) return [];
+ return values
+ .filter((value): value is string => typeof value === "string")
+ .map((value) => redactText(value, maxLength))
+ .filter(Boolean)
+ .slice(0, maxItems);
+}
+
+export function containsLikelySecret(value: string): boolean {
+ for (const pattern of [QUERY_SECRET, KEY_VALUE_SECRET, PREFIX_SECRET, PRIVATE_KEY]) {
+ pattern.lastIndex = 0;
+ if (pattern.test(value)) return true;
+ }
+ return false;
+}
diff --git a/lib/orchestration/repo-memory.test.ts b/lib/orchestration/repo-memory.test.ts
new file mode 100644
index 00000000..dda10afc
--- /dev/null
+++ b/lib/orchestration/repo-memory.test.ts
@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+ ingestManualUserTest,
+ searchRepoMemory,
+ updateRepoMemoryLifecycle,
+ upsertRepoMemory,
+} from "./repo-memory";
+
+const roots: string[] = [];
+async function project() {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "mso-rasmic-memory-"));
+ roots.push(root);
+ await fs.writeFile(path.join(root, "package.json"), JSON.stringify({ name: "fixture" }));
+ return root;
+}
+
+afterEach(async () => {
+ await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+});
+
+describe("repo-local structured memory", () => {
+ it("does not create .agent during a read-only search when memory is absent", async () => {
+ const root = await project();
+ await expect(searchRepoMemory(root, { query: "freeze" })).resolves.toEqual([]);
+ await expect(fs.lstat(path.join(root, ".agent"))).rejects.toMatchObject({ code: "ENOENT" });
+ });
+
+ it("creates portable task/debug/test memory and ranks current confirmed facts above stale records", async () => {
+ const root = await project();
+ await upsertRepoMemory(root, {
+ kind: "debug",
+ title: "Old freeze diagnosis",
+ summary: "renderer freeze after reconnect",
+ source: "agent",
+ status: "active",
+ confidence: 0.7,
+ importance: 0.6,
+ lastVerified: "2024-01-01T00:00:00Z",
+ tags: ["freeze"],
+ });
+ const current = await upsertRepoMemory(root, {
+ kind: "debug",
+ title: "Confirmed freeze diagnosis",
+ summary: "renderer freeze after reconnect",
+ source: "agent",
+ status: "confirmed",
+ confidence: 0.95,
+ importance: 0.9,
+ lastVerified: new Date().toISOString(),
+ tags: ["freeze"],
+ });
+ const hits = await searchRepoMemory(root, { query: "renderer freeze reconnect", limit: 5 });
+ expect(hits[0].record.id).toBe(current.id);
+ expect(hits[0].score).toBeGreaterThan(hits[1].score);
+ await expect(fs.lstat(path.join(root, ".agent", "memory", "debug"))).resolves.toMatchObject({});
+ });
+
+ it("ingests the user's failed manual test as high-confidence active test memory", async () => {
+ const root = await project();
+ const record = await ingestManualUserTest(root, {
+ observation: "I tested the game and it still freezes after reconnect",
+ result: "fail",
+ environment: "mobile PWA",
+ scope: ["src/game/runtime.ts"],
+ });
+ expect(record).toMatchObject({
+ kind: "test",
+ source: "user-manual",
+ result: "fail",
+ status: "active",
+ confidence: 1,
+ environment: "mobile PWA",
+ });
+ const [hit] = await searchRepoMemory(root, { query: "freeze reconnect", kinds: ["test"] });
+ expect(hit.record.id).toBe(record.id);
+ expect(hit.record.failed).toContain("still freezes");
+ });
+
+ it("redacts credentials before persistence", async () => {
+ const root = await project();
+ const record = await upsertRepoMemory(root, {
+ kind: "task",
+ title: "Deploy check",
+ summary: "Authorization: Bearer ghp_1234567890abcdef and token=top-secret-value",
+ source: "system",
+ });
+ expect(JSON.stringify(record)).not.toContain("1234567890abcdef");
+ expect(JSON.stringify(record)).not.toContain("top-secret-value");
+ const body = (await searchRepoMemory(root, { query: "deploy", kinds: ["task"] }))[0].record;
+ expect(JSON.stringify(body)).toContain("[redacted]");
+ });
+
+ it("supersedes old memory and excludes it from default retrieval", async () => {
+ const root = await project();
+ const old = await upsertRepoMemory(root, {
+ kind: "decision",
+ title: "Old deployment decision",
+ summary: "use route A",
+ source: "agent",
+ status: "confirmed",
+ });
+ const replacement = await upsertRepoMemory(root, {
+ kind: "decision",
+ title: "New deployment decision",
+ summary: "use route B",
+ source: "agent",
+ status: "confirmed",
+ supersedes: [old.id],
+ });
+ const current = await searchRepoMemory(root, { query: "deployment decision", kinds: ["decision"] });
+ expect(current.map((hit) => hit.record.id)).toEqual([replacement.id]);
+ const history = await searchRepoMemory(root, { query: "deployment decision", kinds: ["decision"], includeHistory: true });
+ expect(history.map((hit) => hit.record.id)).toEqual(expect.arrayContaining([replacement.id, old.id]));
+ expect(history.find((hit) => hit.record.id === old.id)?.record.status).toBe("superseded");
+ });
+
+ it("supports explicit lifecycle updates", async () => {
+ const root = await project();
+ const record = await upsertRepoMemory(root, {
+ kind: "failure", title: "Temporary failure", summary: "failed once", source: "agent",
+ });
+ const archived = await updateRepoMemoryLifecycle(root, record.id, "archived");
+ expect(archived.status).toBe("archived");
+ await expect(searchRepoMemory(root, { query: "temporary failure" })).resolves.toEqual([]);
+ });
+ it("ranks a current failed manual user test above a conflicting automated pass", async () => {
+ const root = await project();
+ await upsertRepoMemory(root, {
+ kind: "test", title: "Reconnect automated smoke", summary: "reconnect freeze check",
+ source: "automation", result: "pass", status: "confirmed", confidence: 1, importance: 0.9,
+ lastVerified: new Date().toISOString(), tags: ["reconnect", "freeze"],
+ });
+ const manual = await ingestManualUserTest(root, {
+ observation: "I tested reconnect and it still freezes", result: "fail", tags: ["reconnect", "freeze"],
+ });
+ const hits = await searchRepoMemory(root, { query: "reconnect freeze", kinds: ["test"] });
+ expect(hits[0].record.id).toBe(manual.id);
+ expect(hits[0].record).toMatchObject({ source: "user-manual", result: "fail" });
+ });
+
+ it("normalizes caller-provided record ids so they cannot escape the memory directory", async () => {
+ const root = await project();
+ const record = await upsertRepoMemory(root, {
+ id: "../../outside", kind: "task", title: "Safe id", summary: "must stay inside .agent", source: "agent",
+ });
+ expect(record.id).not.toContain("/");
+ await expect(fs.lstat(path.join(root, "outside.json"))).rejects.toMatchObject({ code: "ENOENT" });
+ const files = await fs.readdir(path.join(root, ".agent/memory/tasks"));
+ expect(files).toHaveLength(1);
+ });
+
+ it("refuses nested symlink escapes during read-only retrieval", async () => {
+ const root = await project();
+ const outside = await fs.mkdtemp(path.join(os.tmpdir(), "mso-rasmic-outside-"));
+ roots.push(outside);
+ await fs.mkdir(path.join(root, ".agent/memory"), { recursive: true });
+ await fs.symlink(outside, path.join(root, ".agent/memory/debug"));
+ await expect(searchRepoMemory(root, { query: "secret", kinds: ["debug"] })).rejects.toThrow(/not a safe directory/i);
+ });
+
+});
diff --git a/lib/orchestration/repo-memory.ts b/lib/orchestration/repo-memory.ts
new file mode 100644
index 00000000..22b64449
--- /dev/null
+++ b/lib/orchestration/repo-memory.ts
@@ -0,0 +1,335 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { redactStrings, redactText } from "./redaction";
+import type {
+ AutomationScriptManifest,
+ EvidenceReceipt,
+ RepoMemoryKind,
+ RepoMemoryLifecycle,
+ RepoMemoryRecord,
+ RepoMemoryResult,
+ RepoMemorySearchHit,
+ RepoMemorySource,
+} from "./types";
+
+const KIND_DIR: Record<RepoMemoryKind, string> = {
+ task: "tasks",
+ debug: "debug",
+ test: "tests",
+ decision: "decisions",
+ failure: "failures",
+};
+const LAYOUT = ["memory/tasks", "memory/debug", "memory/tests", "memory/decisions", "memory/failures", "recipes", "scripts", "evidence"] as const;
+const MAX_RECORD_BYTES = 64 * 1024;
+const MAX_RECORDS_PER_KIND = 500;
+
+async function assertDirectoryNoSymlink(dir: string): Promise<void> {
+ const stat = await fs.lstat(dir).catch(() => null);
+ if (!stat) return;
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`repo memory path is not a safe directory: ${dir}`);
+}
+
+async function projectRoot(projectPath: string): Promise<string> {
+ const absolute = path.resolve(projectPath);
+ const stat = await fs.lstat(absolute).catch(() => null);
+ if (!stat?.isDirectory() || stat.isSymbolicLink()) throw new Error("project path must be a real directory");
+ return fs.realpath(absolute);
+}
+
+async function existingRepoMemoryLayout(projectPath: string): Promise<string | null> {
+ const root = await projectRoot(projectPath);
+ const agent = path.join(root, ".agent");
+ const stat = await fs.lstat(agent).catch(() => null);
+ if (!stat) return null;
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("repo memory .agent path is not a safe directory");
+ for (const relative of LAYOUT) {
+ const candidate = path.join(agent, relative);
+ const nested = await fs.lstat(candidate).catch(() => null);
+ if (nested && (!nested.isDirectory() || nested.isSymbolicLink())) {
+ throw new Error(`repo memory path is not a safe directory: ${candidate}`);
+ }
+ }
+ return agent;
+}
+
+export async function ensureRepoMemoryLayout(projectPath: string): Promise<string> {
+ const root = await projectRoot(projectPath);
+ const agent = path.join(root, ".agent");
+ await assertDirectoryNoSymlink(agent);
+ await fs.mkdir(agent, { recursive: true, mode: 0o700 });
+ for (const relative of LAYOUT) {
+ const dir = path.join(agent, relative);
+ await assertDirectoryNoSymlink(dir);
+ await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+ }
+ return agent;
+}
+
+function clamp01(value: number | undefined, fallback: number): number {
+ const n = value ?? fallback;
+ if (!Number.isFinite(n)) return fallback;
+ return Math.max(0, Math.min(1, Math.round(n * 1000) / 1000));
+}
+
+function safeIso(value?: string): string | undefined {
+ if (!value) return undefined;
+ const timestamp = Date.parse(value);
+ if (!Number.isFinite(timestamp)) throw new Error("memory timestamp must be ISO-8601");
+ return new Date(timestamp).toISOString();
+}
+
+function safeStatus(value?: RepoMemoryLifecycle): RepoMemoryLifecycle {
+ return ["active", "confirmed", "superseded", "archived"].includes(String(value)) ? value! : "active";
+}
+
+function safeResult(value?: RepoMemoryResult): RepoMemoryResult | undefined {
+ return value && ["pass", "fail", "unknown"].includes(value) ? value : undefined;
+}
+
+function safeSource(value?: RepoMemorySource): RepoMemorySource {
+ return value && ["agent", "system", "user-manual", "automation"].includes(value) ? value : "agent";
+}
+
+function memoryRecord(input: {
+ id?: string;
+ kind: RepoMemoryKind;
+ status?: RepoMemoryLifecycle;
+ title: string;
+ summary: string;
+ source?: RepoMemorySource;
+ result?: RepoMemoryResult;
+ observation?: string;
+ happened?: string;
+ learned?: string;
+ failed?: string;
+ worked?: string;
+ reuse?: string;
+ confidence?: number;
+ importance?: number;
+ lastVerified?: string;
+ scope?: string[];
+ tags?: string[];
+ commit?: string;
+ environment?: string;
+ supersedes?: string[];
+ createdAt?: string;
+}): RepoMemoryRecord {
+ if (!Object.prototype.hasOwnProperty.call(KIND_DIR, input.kind)) throw new Error("invalid repo memory kind");
+ const now = new Date().toISOString();
+ const title = redactText(input.title, 160);
+ const summary = redactText(input.summary, 2400);
+ if (!title || !summary) throw new Error("repo memory title and summary are required");
+ const optional = (value: string | undefined, max = 2400) => value ? redactText(value, max) || undefined : undefined;
+ return {
+ schemaVersion: 1,
+ id: input.id ? safeArtifactId(input.id) : `mem_${randomUUID()}`,
+ kind: input.kind,
+ status: safeStatus(input.status),
+ title,
+ summary,
+ source: safeSource(input.source),
+ ...(safeResult(input.result) ? { result: safeResult(input.result) } : {}),
+ ...(optional(input.observation) ? { observation: optional(input.observation) } : {}),
+ ...(optional(input.happened) ? { happened: optional(input.happened) } : {}),
+ ...(optional(input.learned) ? { learned: optional(input.learned) } : {}),
+ ...(optional(input.failed) ? { failed: optional(input.failed) } : {}),
+ ...(optional(input.worked) ? { worked: optional(input.worked) } : {}),
+ ...(optional(input.reuse) ? { reuse: optional(input.reuse) } : {}),
+ confidence: clamp01(input.confidence, input.source === "user-manual" ? 1 : 0.8),
+ importance: clamp01(input.importance, 0.5),
+ ...(safeIso(input.lastVerified) ? { lastVerified: safeIso(input.lastVerified) } : {}),
+ scope: redactStrings(input.scope, 40, 240),
+ tags: redactStrings(input.tags, 40, 80).map((tag) => tag.toLowerCase()),
+ ...(optional(input.commit, 80) ? { commit: optional(input.commit, 80) } : {}),
+ ...(optional(input.environment, 400) ? { environment: optional(input.environment, 400) } : {}),
+ supersedes: redactStrings(input.supersedes, 40, 120),
+ createdAt: safeIso(input.createdAt) ?? now,
+ updatedAt: now,
+ };
+}
+
+function safeArtifactId(value: string): string {
+ const normalized = redactText(value, 120).replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^\.+|\.+$/g, "");
+ if (!normalized || normalized === "." || normalized === "..") throw new Error("invalid artifact id");
+ return normalized;
+}
+
+async function atomicWriteJson(file: string, value: unknown): Promise<void> {
+ const body = `${JSON.stringify(value, null, 2)}\n`;
+ if (Buffer.byteLength(body, "utf8") > MAX_RECORD_BYTES) throw new Error("repo memory record exceeds 64 KiB");
+ const tmp = `${file}.${randomUUID()}.tmp`;
+ await fs.writeFile(tmp, body, { encoding: "utf8", mode: 0o600, flag: "wx" });
+ await fs.rename(tmp, file);
+}
+
+async function readRecordFile(file: string): Promise<RepoMemoryRecord | null> {
+ const stat = await fs.lstat(file).catch(() => null);
+ if (!stat?.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > MAX_RECORD_BYTES) return null;
+ try {
+ const parsed = JSON.parse(await fs.readFile(file, "utf8")) as RepoMemoryRecord;
+ if (parsed?.schemaVersion !== 1 || typeof parsed.id !== "string" || !KIND_DIR[parsed.kind]) return null;
+ return parsed;
+ } catch {
+ return null;
+ }
+}
+
+async function locateRecord(projectPath: string, id: string): Promise<{ file: string; record: RepoMemoryRecord } | null> {
+ const agent = await ensureRepoMemoryLayout(projectPath);
+ for (const kind of Object.keys(KIND_DIR) as RepoMemoryKind[]) {
+ const dir = path.join(agent, "memory", KIND_DIR[kind]);
+ const names = (await fs.readdir(dir).catch(() => [] as string[])).filter((name) => name.endsWith(".json")).slice(0, MAX_RECORDS_PER_KIND);
+ for (const name of names) {
+ const file = path.join(dir, name);
+ const record = await readRecordFile(file);
+ if (record?.id === id) return { file, record };
+ }
+ }
+ return null;
+}
+
+export async function upsertRepoMemory(projectPath: string, input: Parameters<typeof memoryRecord>[0]): Promise<RepoMemoryRecord> {
+ const agent = await ensureRepoMemoryLayout(projectPath);
+ const prior = input.id ? await locateRecord(projectPath, input.id) : null;
+ const record = memoryRecord({ ...input, createdAt: prior?.record.createdAt ?? input.createdAt });
+ const dir = path.join(agent, "memory", KIND_DIR[record.kind]);
+ const file = prior?.file ?? path.join(dir, `${record.createdAt.slice(0, 10)}-${record.id}.json`);
+ if (prior && path.dirname(prior.file) !== dir) throw new Error("repo memory kind cannot change in-place");
+ await atomicWriteJson(file, record);
+
+ for (const supersededId of record.supersedes) {
+ const old = await locateRecord(projectPath, supersededId);
+ if (!old || old.record.status === "superseded") continue;
+ await atomicWriteJson(old.file, { ...old.record, status: "superseded", updatedAt: new Date().toISOString() });
+ }
+ return record;
+}
+
+export async function updateRepoMemoryLifecycle(projectPath: string, id: string, status: RepoMemoryLifecycle): Promise<RepoMemoryRecord> {
+ const located = await locateRecord(projectPath, id);
+ if (!located) throw new Error("repo memory record not found");
+ const record = { ...located.record, status: safeStatus(status), updatedAt: new Date().toISOString() };
+ await atomicWriteJson(located.file, record);
+ return record;
+}
+
+function tokens(value: string): string[] {
+ return [...new Set(value.toLowerCase().match(/[a-z0-9][a-z0-9._/-]{1,}/g) ?? [])].slice(0, 60);
+}
+
+function rank(record: RepoMemoryRecord, query: string, nowMs: number): RepoMemorySearchHit {
+ const text = [record.title, record.summary, record.observation, record.learned, record.failed, record.worked, record.reuse, ...record.tags, ...record.scope]
+ .filter(Boolean).join(" ").toLowerCase();
+ const queryTokens = tokens(query);
+ const matches = queryTokens.filter((token) => text.includes(token)).length;
+ const lexical = queryTokens.length ? matches / queryTokens.length : 0.25;
+ const verifiedAt = Date.parse(record.lastVerified ?? record.updatedAt);
+ const ageDays = Math.max(0, (nowMs - (Number.isFinite(verifiedAt) ? verifiedAt : 0)) / 86_400_000);
+ const freshness = Math.max(0, 1 - Math.min(ageDays, 365) / 365);
+ const lifecycle = record.status === "confirmed" ? 1 : record.status === "active" ? 0.8 : record.status === "superseded" ? 0.25 : 0.15;
+ const manualAuthority = record.source === "user-manual" ? (record.result === "fail" ? 1 : 0.85) : 0;
+ const score = lexical * 0.45 + record.confidence * 0.14 + record.importance * 0.12 + freshness * 0.09 + lifecycle * 0.08 + manualAuthority * 0.12;
+ return { record, score: Math.round(score * 10000) / 10000, ageDays: Math.round(ageDays * 10) / 10 };
+}
+
+export async function searchRepoMemory(projectPath: string, input: {
+ query?: string;
+ kinds?: RepoMemoryKind[];
+ limit?: number;
+ includeHistory?: boolean;
+} = {}): Promise<RepoMemorySearchHit[]> {
+ const agent = await existingRepoMemoryLayout(projectPath);
+ if (!agent) return [];
+ const kinds = input.kinds?.length ? input.kinds : Object.keys(KIND_DIR) as RepoMemoryKind[];
+ const now = Date.now();
+ const hits: RepoMemorySearchHit[] = [];
+ for (const kind of kinds) {
+ const dir = path.join(agent, "memory", KIND_DIR[kind]);
+ const names = (await fs.readdir(dir).catch(() => [] as string[])).filter((name) => name.endsWith(".json")).slice(0, MAX_RECORDS_PER_KIND);
+ for (const name of names) {
+ const record = await readRecordFile(path.join(dir, name));
+ if (!record) continue;
+ if (!input.includeHistory && (record.status === "superseded" || record.status === "archived")) continue;
+ hits.push(rank(record, input.query ?? "", now));
+ }
+ }
+ return hits
+ .filter((hit) => !input.query || hit.score >= 0.15)
+ .sort((a, b) => b.score - a.score || b.record.updatedAt.localeCompare(a.record.updatedAt))
+ .slice(0, Math.max(1, Math.min(input.limit ?? 7, 20)));
+}
+
+export async function ingestManualUserTest(projectPath: string, input: {
+ observation: string;
+ result: Exclude<RepoMemoryResult, "unknown">;
+ title?: string;
+ environment?: string;
+ scope?: string[];
+ tags?: string[];
+ commit?: string;
+}): Promise<RepoMemoryRecord> {
+ const observation = redactText(input.observation, 2400);
+ return upsertRepoMemory(projectPath, {
+ kind: "test",
+ title: input.title ?? `Manual user test: ${input.result}`,
+ summary: observation,
+ observation,
+ source: "user-manual",
+ result: input.result,
+ status: input.result === "pass" ? "confirmed" : "active",
+ confidence: 1,
+ importance: input.result === "fail" ? 0.9 : 0.7,
+ lastVerified: new Date().toISOString(),
+ environment: input.environment,
+ scope: input.scope,
+ tags: ["manual-test", input.result, ...(input.tags ?? [])],
+ commit: input.commit,
+ happened: observation,
+ ...(input.result === "fail" ? { failed: observation } : { worked: observation }),
+ reuse: input.result === "fail" ? "Use this observation as regression/debug evidence before declaring the related behavior healthy." : "Use as confirmed manual verification while environment and commit remain relevant.",
+ });
+}
+
+export async function writeEvidenceReceipt(projectPath: string, receipt: EvidenceReceipt): Promise<string> {
+ const agent = await ensureRepoMemoryLayout(projectPath);
+ const file = path.join(agent, "evidence", `${receipt.createdAt.slice(0, 10)}-${receipt.workflow}.json`);
+ await atomicWriteJson(file, receipt);
+ return path.relative(await projectRoot(projectPath), file);
+}
+
+export async function writePortableRecipe(projectPath: string, recipe: unknown, id: string): Promise<string> {
+ const agent = await ensureRepoMemoryLayout(projectPath);
+ const file = path.join(agent, "recipes", `${safeArtifactId(id)}.json`);
+ await atomicWriteJson(file, recipe);
+ return path.relative(await projectRoot(projectPath), file);
+}
+
+export async function writeAutomationScript(projectPath: string, script: unknown, id: string, candidate = true): Promise<string> {
+ const agent = await ensureRepoMemoryLayout(projectPath);
+ const suffix = candidate ? ".candidate.json" : ".json";
+ const file = path.join(agent, "scripts", `${safeArtifactId(id)}${suffix}`);
+ await atomicWriteJson(file, script);
+ if (!candidate) await fs.rm(path.join(agent, "scripts", `${safeArtifactId(id)}.candidate.json`), { force: true }).catch(() => undefined);
+ return path.relative(await projectRoot(projectPath), file);
+}
+
+export async function readAutomationScript(projectPath: string, id: string): Promise<AutomationScriptManifest | null> {
+ const agent = await existingRepoMemoryLayout(projectPath);
+ if (!agent) return null;
+ const safeId = safeArtifactId(id);
+ for (const name of [`${safeId}.json`, `${safeId}.candidate.json`]) {
+ const file = path.join(agent, "scripts", name);
+ const stat = await fs.lstat(file).catch(() => null);
+ if (!stat?.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > MAX_RECORD_BYTES) continue;
+ try {
+ const parsed = JSON.parse(await fs.readFile(file, "utf8")) as AutomationScriptManifest;
+ if (parsed?.schemaVersion !== 1 || parsed.id !== id || !Array.isArray(parsed.steps) || !parsed.steps.length) continue;
+ if (parsed.status !== "candidate" && parsed.status !== "tested") continue;
+ return parsed;
+ } catch {
+ continue;
+ }
+ }
+ return null;
+}
diff --git a/lib/orchestration/standalone.test.ts b/lib/orchestration/standalone.test.ts
new file mode 100644
index 00000000..c0922958
--- /dev/null
+++ b/lib/orchestration/standalone.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const productionFiles = [
+ "types.ts",
+ "classifier.ts",
+ "redaction.ts",
+ "evidence.ts",
+ "repo-memory.ts",
+ "automation.ts",
+];
+
+describe("RASMIC standalone invariant", () => {
+ it("contains no hard-coded sibling checkout or machine-specific project path", async () => {
+ const root = path.resolve(__dirname);
+ const source = (await Promise.all(productionFiles.map((name) => fs.readFile(path.join(root, name), "utf8")))).join("\n");
+ expect(source).not.toMatch(/\/home\/[^\s"']+\/projects\//);
+ expect(source).not.toMatch(/~\/projects\//);
+ expect(source).not.toMatch(/\.\.\/\.\.\/\.\.\/projects\//);
+ });
+
+ it("keeps repo-local portability rooted in .agent rather than an MSO-private runtime path", async () => {
+ const source = await fs.readFile(path.resolve(__dirname, "repo-memory.ts"), "utf8");
+ expect(source).toContain('path.join(root, ".agent")');
+ expect(source).not.toContain('path.join(root, ".mso")');
+ });
+});
diff --git a/lib/orchestration/types.ts b/lib/orchestration/types.ts
new file mode 100644
index 00000000..024c0f86
--- /dev/null
+++ b/lib/orchestration/types.ts
@@ -0,0 +1,143 @@
+export type RiskLevel = "low" | "medium" | "high";
+export type ComplexityLevel = "light" | "medium" | "heavy";
+export type ContentionLevel = "none" | "possible" | "high";
+export type MemoryRelevance = "low" | "medium" | "high";
+export type IsolationMode = "direct" | "optional-worktree" | "isolated-worktree";
+export type VerificationLevel = "targeted" | "affected" | "full";
+export type CleanupState = "not-required" | "pending" | "complete";
+
+export type TaskClassification = {
+ risk: RiskLevel;
+ complexity: ComplexityLevel;
+ contention: ContentionLevel;
+ memoryRelevance: MemoryRelevance;
+ isolation: IsolationMode;
+ verification: VerificationLevel;
+ reasons: string[];
+ sharedResourceWarnings: string[];
+};
+
+export type WorkflowOrchestrationSnapshot = TaskClassification & {
+ baseCommit?: string;
+ baseBranch?: string;
+ changedPaths: string[];
+ affectedPaths: string[];
+ reservedResources: string[];
+ overlappingPaths: string[];
+ overlappingResources: string[];
+ activeProjectWorkflows: number;
+ conflictingWorkflowCount: number;
+ memoryHits: number;
+ contextEstimateTokens: number;
+ cleanupState: CleanupState;
+ workspacePath?: string;
+ recipeUsed?: string;
+ createdAt: string;
+};
+
+export type EvidenceStatus = "pass" | "fail" | "warn" | "not-run";
+
+export type EvidenceItem = {
+ name: string;
+ status: EvidenceStatus;
+ detail?: string;
+};
+
+export type EvidenceReceipt = {
+ schemaVersion: 1;
+ workflow: string;
+ repo?: string;
+ baseCommit?: string;
+ finalCommit?: string;
+ environment?: string;
+ claims: string[];
+ tests: EvidenceItem[];
+ build: EvidenceItem[];
+ deployment: EvidenceItem[];
+ health: EvidenceItem[];
+ artifacts: string[];
+ manualVerification: EvidenceItem[];
+ knownRisks: string[];
+ createdAt: string;
+};
+
+export type EvidenceInput = Partial<{
+ environment: string;
+ claims: string[];
+ tests: string[];
+ build: string[];
+ deployment: string[];
+ health: string[];
+ artifacts: string[];
+ manualVerification: string[];
+ knownRisks: string[];
+}>;
+
+export type RepoMemoryKind = "task" | "debug" | "test" | "decision" | "failure";
+export type RepoMemoryLifecycle = "active" | "confirmed" | "superseded" | "archived";
+export type RepoMemorySource = "agent" | "system" | "user-manual" | "automation";
+export type RepoMemoryResult = "pass" | "fail" | "unknown";
+
+export type RepoMemoryRecord = {
+ schemaVersion: 1;
+ id: string;
+ kind: RepoMemoryKind;
+ status: RepoMemoryLifecycle;
+ title: string;
+ summary: string;
+ source: RepoMemorySource;
+ result?: RepoMemoryResult;
+ observation?: string;
+ happened?: string;
+ learned?: string;
+ failed?: string;
+ worked?: string;
+ reuse?: string;
+ confidence: number;
+ importance: number;
+ lastVerified?: string;
+ scope: string[];
+ tags: string[];
+ commit?: string;
+ environment?: string;
+ supersedes: string[];
+ createdAt: string;
+ updatedAt: string;
+};
+
+export type RepoMemorySearchHit = {
+ record: RepoMemoryRecord;
+ score: number;
+ ageDays: number;
+};
+
+export type AutomationStage = "observed" | "candidate" | "verified";
+export type AutomationAssessment = {
+ stage: AutomationStage;
+ successRate: number;
+ stableSteps: boolean;
+ scriptCandidate: boolean;
+ reasons: string[];
+};
+
+export type AutomationScriptManifest = {
+ schemaVersion: 1;
+ id: string;
+ recipeId: string;
+ status: "candidate" | "tested";
+ intent: string;
+ project?: string;
+ steps: Array<{ tool: string; args?: Record<string, string | number | boolean> }>;
+ output: { format: "structured-json" };
+ gates: {
+ repeatedPattern: boolean;
+ stableSteps: boolean;
+ clearInputs: boolean;
+ clearOutputs: boolean;
+ sideEffectsUnderstood: boolean;
+ secretSafe: boolean;
+ tested: boolean;
+ };
+ createdAt: string;
+ updatedAt: string;
+};
diff --git a/lib/skills/memory-contention.test.ts b/lib/skills/memory-contention.test.ts
new file mode 100644
index 00000000..066a0517
--- /dev/null
+++ b/lib/skills/memory-contention.test.ts
@@ -0,0 +1,85 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-contention-memory-"));
+process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
+const memory = await import("./memory");
+
+const orchestration = (affectedPaths: string[], reservedResources: string[]) => ({
+ risk: "medium" as const,
+ complexity: "medium" as const,
+ contention: "none" as const,
+ memoryRelevance: "medium" as const,
+ isolation: "optional-worktree" as const,
+ verification: "affected" as const,
+ reasons: ["contained feature"],
+ sharedResourceWarnings: [],
+ changedPaths: [],
+ affectedPaths,
+ reservedResources,
+ overlappingPaths: [],
+ overlappingResources: [],
+ activeProjectWorkflows: 0,
+ conflictingWorkflowCount: 0,
+ memoryHits: 0,
+ contextEstimateTokens: 20,
+ cleanupState: "pending" as const,
+ workspacePath: "/repo",
+ createdAt: new Date().toISOString(),
+});
+
+describe("workflow scope collision metadata", () => {
+ beforeEach(async () => {
+ await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });
+ memory.resetSkillMemoryCache();
+ });
+ afterAll(async () => { await fs.rm(dir, { recursive: true, force: true }); });
+
+ it("detects overlapping path scopes and reserved shared resources before merge conflict", async () => {
+ const first = await memory.startWorkflow({
+ actor: "mcp:first",
+ intent: "update auth flow",
+ project: "/repo",
+ orchestration: orchestration(["src/auth"], ["port:4173", "database:development"]),
+ });
+
+ await expect(memory.summarizeProjectContention(
+ "/repo",
+ ["src/auth/session.ts"],
+ ["database:development"],
+ )).resolves.toMatchObject({
+ activeWorkflowCount: 1,
+ conflictingWorkflowCount: 1,
+ overlappingPaths: ["src/auth/session.ts"],
+ overlappingResources: ["database:development"],
+ });
+
+ await expect(memory.summarizeProjectContention(
+ "/repo",
+ ["src/builder"],
+ ["port:9000"],
+ )).resolves.toMatchObject({
+ activeWorkflowCount: 1,
+ conflictingWorkflowCount: 0,
+ overlappingPaths: [],
+ overlappingResources: [],
+ });
+
+ await memory.cancelWorkflow({ actor: "mcp:first", workflowId: first.workflow.id });
+ });
+
+ it("does not expose another workflow actor or intent in the contention summary", async () => {
+ await memory.startWorkflow({
+ actor: "mcp:private-owner",
+ intent: "private internal task description",
+ project: "/repo",
+ orchestration: orchestration(["src/shared"], ["queue:jobs"]),
+ });
+ const result = await memory.summarizeProjectContention("/repo", ["src/shared/file.ts"], ["queue:jobs"]);
+ const serialized = JSON.stringify(result);
+ expect(serialized).not.toContain("private-owner");
+ expect(serialized).not.toContain("private internal task description");
+ });
+});
diff --git a/lib/skills/memory.ts b/lib/skills/memory.ts
index ce3b3241..dc74c952 100644
--- a/lib/skills/memory.ts
+++ b/lib/skills/memory.ts
@@ -5,6 +5,7 @@ import os from "os";
import path from "path";
import { embedSkillText, hybridSemanticScore, normalizeSemanticText, SKILL_EMBEDDING_VERSION } from "./semantic";
import { allows, type Scope } from "@/lib/mcp/scope";
+import type { WorkflowOrchestrationSnapshot } from "@/lib/orchestration/types";
export type WorkflowStepState = "completed" | "failed" | "denied" | "rate_limited" | "invalid_args";
@@ -28,6 +29,7 @@ export type ActiveWorkflow = {
intent: string;
project?: string;
constraints?: string;
+ orchestration?: WorkflowOrchestrationSnapshot;
startedAt: string;
steps: WorkflowStep[];
};
@@ -100,6 +102,40 @@ function storePath(): string {
return (env || path.join(os.homedir(), ".mso", "skill-memory.json")).replace(/^~(?=$|\/)/, os.homedir());
}
+function sanitizeOrchestration(value: unknown): WorkflowOrchestrationSnapshot | undefined {
+ if (!value || typeof value !== "object") return undefined;
+ const row = value as Partial<WorkflowOrchestrationSnapshot>;
+ const risks = ["low", "medium", "high"] as const;
+ const complexities = ["light", "medium", "heavy"] as const;
+ const contentions = ["none", "possible", "high"] as const;
+ const relevances = ["low", "medium", "high"] as const;
+ const isolations = ["direct", "optional-worktree", "isolated-worktree"] as const;
+ const verifications = ["targeted", "affected", "full"] as const;
+ if (!risks.includes(row.risk as never) || !complexities.includes(row.complexity as never) ||
+ !contentions.includes(row.contention as never) || !relevances.includes(row.memoryRelevance as never) ||
+ !isolations.includes(row.isolation as never) || !verifications.includes(row.verification as never)) return undefined;
+ const strings = (candidate: unknown, maxItems: number, maxLen: number) => Array.isArray(candidate)
+ ? candidate.filter((item): item is string => typeof item === "string").map((item) => safeMemoryText(item, maxLen)).filter(Boolean).slice(0, maxItems)
+ : [];
+ return {
+ risk: row.risk!, complexity: row.complexity!, contention: row.contention!, memoryRelevance: row.memoryRelevance!,
+ isolation: row.isolation!, verification: row.verification!, reasons: strings(row.reasons, 12, 240),
+ sharedResourceWarnings: strings(row.sharedResourceWarnings, 12, 240), changedPaths: strings(row.changedPaths, 80, 240),
+ affectedPaths: strings(row.affectedPaths, 80, 240), reservedResources: strings(row.reservedResources, 40, 160),
+ overlappingPaths: strings(row.overlappingPaths, 80, 240), overlappingResources: strings(row.overlappingResources, 40, 160),
+ activeProjectWorkflows: Math.max(0, Math.min(100, Math.round(Number(row.activeProjectWorkflows) || 0))),
+ conflictingWorkflowCount: Math.max(0, Math.min(100, Math.round(Number(row.conflictingWorkflowCount) || 0))),
+ memoryHits: Math.max(0, Math.min(100, Math.round(Number(row.memoryHits) || 0))),
+ contextEstimateTokens: Math.max(0, Math.min(1_000_000, Math.round(Number(row.contextEstimateTokens) || 0))),
+ cleanupState: row.cleanupState === "pending" || row.cleanupState === "complete" ? row.cleanupState : "not-required",
+ ...(typeof row.workspacePath === "string" ? { workspacePath: safeMemoryText(row.workspacePath, 240) } : {}),
+ ...(typeof row.baseCommit === "string" ? { baseCommit: safeMemoryText(row.baseCommit, 80) } : {}),
+ ...(typeof row.baseBranch === "string" ? { baseBranch: safeMemoryText(row.baseBranch, 160) } : {}),
+ ...(typeof row.recipeUsed === "string" ? { recipeUsed: safeMemoryText(row.recipeUsed, 120) } : {}),
+ createdAt: typeof row.createdAt === "string" && Number.isFinite(Date.parse(row.createdAt)) ? new Date(row.createdAt).toISOString() : new Date(0).toISOString(),
+ };
+}
+
function isActiveWorkflow(value: unknown): value is ActiveWorkflow {
if (!value || typeof value !== "object") return false;
const row = value as Partial<ActiveWorkflow>;
@@ -121,6 +157,7 @@ function normalizeActive(value: unknown): ActiveWorkflowBuckets {
intent: safeMemoryText(candidate.intent, 1000),
project: candidate.project ? safeMemoryText(candidate.project, 240) || undefined : undefined,
constraints: candidate.constraints ? safeMemoryText(candidate.constraints, 500) || undefined : undefined,
+ orchestration: sanitizeOrchestration(candidate.orchestration),
steps: candidate.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
};
continue;
@@ -135,6 +172,7 @@ function normalizeActive(value: unknown): ActiveWorkflowBuckets {
intent: safeMemoryText(workflow.intent, 1000),
project: workflow.project ? safeMemoryText(workflow.project, 240) || undefined : undefined,
constraints: workflow.constraints ? safeMemoryText(workflow.constraints, 500) || undefined : undefined,
+ orchestration: sanitizeOrchestration(workflow.orchestration),
steps: workflow.steps.map(sanitizeStoredStep).filter((step): step is WorkflowStep => Boolean(step)),
};
}
@@ -276,6 +314,8 @@ const SAFE_TOOL_ARGS: Record<string, readonly string[]> = {
projects_list: ["query", "limit", "offset"],
project_capabilities: ["project"],
project_function_call: ["project", "name"],
+ project_memory_search: ["project", "query", "kind", "limit", "include_history"],
+ project_memory_upsert: ["project", "kind", "source", "result", "status"],
skills_list: ["project", "trust", "limit", "offset"],
skills_read: ["name"],
screen_capture: ["shell", "width", "height"],
@@ -464,6 +504,7 @@ export async function startWorkflow(input: {
intent: string;
project?: string;
constraints?: string;
+ orchestration?: WorkflowOrchestrationSnapshot;
}): Promise<{ workflow: ActiveWorkflow; activeWorkflowCount: number }> {
const actor = actorKey(input.actor);
const scope: Scope = input.scope ?? "read";
@@ -482,6 +523,7 @@ export async function startWorkflow(input: {
intent,
project: input.project ? safeMemoryText(input.project, 240) || undefined : undefined,
constraints: input.constraints ? safeMemoryText(input.constraints, 500) || undefined : undefined,
+ orchestration: sanitizeOrchestration(input.orchestration),
startedAt: new Date().toISOString(),
steps: [],
};
@@ -490,6 +532,59 @@ export async function startWorkflow(input: {
return { workflow, activeWorkflowCount: Object.keys(store.active[actor]).length };
}
+export type ProjectContentionSummary = {
+ activeWorkflowCount: number;
+ conflictingWorkflowCount: number;
+ overlappingPaths: string[];
+ overlappingResources: string[];
+};
+
+const normalizedProject = (value?: string) => value?.trim().replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase() ?? "";
+const pathScopeOverlaps = (a: string, b: string): boolean => {
+ const left = a.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+ const right = b.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+ return Boolean(left && right && (left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)));
+};
+
+export async function summarizeProjectContention(
+ project?: string, affectedPaths: string[] = [], reservedResources: string[] = [],
+): Promise<ProjectContentionSummary> {
+ const key = normalizedProject(project);
+ if (!key) return { activeWorkflowCount: 0, conflictingWorkflowCount: 0, overlappingPaths: [], overlappingResources: [] };
+ const store = await loadStore();
+ let changed = false, activeWorkflowCount = 0, conflictingWorkflowCount = 0;
+ const overlappingPaths = new Set<string>(), overlappingResources = new Set<string>();
+ const resources = reservedResources.map((value) => value.trim().toLowerCase()).filter(Boolean);
+ for (const actor of Object.keys(store.active)) {
+ changed = pruneStaleWorkflows(store, actor) || changed;
+ for (const workflow of Object.values(store.active[actor] ?? {})) {
+ if (normalizedProject(workflow.project) !== key) continue;
+ activeWorkflowCount += 1;
+ let conflict = false;
+ for (const requested of affectedPaths) {
+ if ((workflow.orchestration?.affectedPaths ?? []).some((active) => pathScopeOverlaps(requested, active))) {
+ overlappingPaths.add(requested); conflict = true;
+ }
+ }
+ const activeResources = (workflow.orchestration?.reservedResources ?? []).map((value) => value.trim().toLowerCase());
+ for (const requested of resources) {
+ if (activeResources.includes(requested)) { overlappingResources.add(requested); conflict = true; }
+ }
+ if (conflict) conflictingWorkflowCount += 1;
+ }
+ }
+ if (changed) await persist(store);
+ return {
+ activeWorkflowCount, conflictingWorkflowCount,
+ overlappingPaths: [...overlappingPaths].slice(0, 80),
+ overlappingResources: [...overlappingResources].slice(0, 40),
+ };
+}
+
+export async function countActiveWorkflowsForProject(project?: string): Promise<number> {
+ return (await summarizeProjectContention(project)).activeWorkflowCount;
+}
+
export async function activeWorkflowForActor(actor?: string, workflowId?: string): Promise<ActiveWorkflow | null> {
if (!actor) return null;
const store = await loadStore();
diff --git a/lib/skills/search-recipe-gate.test.ts b/lib/skills/search-recipe-gate.test.ts
new file mode 100644
index 00000000..796d620a
--- /dev/null
+++ b/lib/skills/search-recipe-gate.test.ts
@@ -0,0 +1,55 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-recipe-gate-"));
+process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
+const memory = await import("./memory");
+const { searchSkillMemory } = await import("./search");
+
+const actor = "mcp:recipe-gate";
+const intent = "verify bounded server health";
+
+async function successfulRun() {
+ const started = await memory.startWorkflow({ actor, scope: "read", intent });
+ await memory.recordWorkflowStep(actor, started.workflow.id, {
+ id: `step-${Date.now()}-${Math.random()}`,
+ tool: "sys_stats",
+ state: "completed",
+ durationMs: 4,
+ ts: new Date().toISOString(),
+ });
+ await memory.finishWorkflow({ actor, recipeActor: actor, workflowId: started.workflow.id, summary: "healthy", success: true });
+}
+
+async function search() {
+ return searchSkillMemory(intent, {
+ recipeAccess: { actor, scope: "read" },
+ projects: [],
+ topK: 20,
+ toolDocs: [{ name: "sys_stats", description: "Live server health", scope: "read", inputSchema: { properties: {} } }],
+ });
+}
+
+describe("reusable recipe recommendation gate", () => {
+ beforeEach(async () => {
+ await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });
+ memory.resetSkillMemoryCache();
+ });
+ afterAll(async () => { await fs.rm(dir, { recursive: true, force: true }); });
+
+ it("keeps a one-off successful trace as observed memory instead of recommending it as a reusable recipe", async () => {
+ await successfulRun();
+ const result = await search();
+ expect(result.hits.some((hit) => hit.kind === "recipe")).toBe(true);
+ expect(result.recommendedRecipe).toBeUndefined();
+ });
+
+ it("allows recommendation after the same route succeeds repeatedly", async () => {
+ await successfulRun();
+ await successfulRun();
+ const result = await search();
+ expect(result.recommendedRecipe).toMatchObject({ kind: "recipe", attempts: 2, successRate: 100 });
+ });
+});
diff --git a/lib/skills/search.ts b/lib/skills/search.ts
index df91c15a..6e281dfa 100644
--- a/lib/skills/search.ts
+++ b/lib/skills/search.ts
@@ -137,6 +137,8 @@ export async function searchSkillMemory(query: string, options: SkillSearchOptio
query: q,
hits: sorted,
catalog: scan,
- recommendedRecipe: sorted.find((h) => h.kind === "recipe" && h.score >= 0.22),
+ recommendedRecipe: sorted.find((h) =>
+ h.kind === "recipe" && h.score >= 0.22 && (h.attempts ?? 0) >= 2 && (h.successRate ?? 0) >= 50,
+ ),
};
}
diff --git a/scripts/mso-agent-runtime.mjs b/scripts/mso-agent-runtime.mjs
index 47c9ced1..a6af8636 100644
--- a/scripts/mso-agent-runtime.mjs
+++ b/scripts/mso-agent-runtime.mjs
@@ -174,7 +174,8 @@ function sessionSystem(agentSession, skillContext = null) {
"For setup, first inspect infrastructure with infra_providers_list and live-check configured providers with infra_provider_doctor.",
"Dokploy, Cloudflare, and Hostinger credentials are entered interactively with `mso provider set <id>` and are never exposed to you; never ask the user to paste API tokens into chat or shell commands.",
"Use dokploy_* and cloudflare_*/hostinger_* tools after the user has configured those providers. Cloudflare DNS must remain per-record and DNS-only unless the user explicitly asks for proxying.",
- "If multiple operational calls are needed, use workflow_start, pass its workflow_id to later calls, verify, then workflow_finish. If the task is abandoned, workflow_cancel.",
+ "If multiple operational calls are needed, use workflow_start, pass its workflow_id to later calls, follow its risk/isolation guidance, verify progressively, then workflow_finish with concrete evidence. If the task is abandoned, workflow_cancel.",
+ "When the user reports a manual test outcome (for example still frozen, fixed, pass, or failed), persist that observation with project_memory_upsert using source=user-manual. Never let an automated pass silently override a newer failed manual user test.",
"Write and exec tools may be denied by the user's approval prompt. Never retry a denied call unchanged.",
"USER.md and MEMORY.md below are a frozen snapshot captured when this MSO session started. Do not silently live-refresh them during this session. Never store secrets in agent memory.",
user ? `\n<USER.md>\n${user}\n</USER.md>` : "",
diff --git a/scripts/mso-agent-tool-router.mjs b/scripts/mso-agent-tool-router.mjs
index ea3d8dd6..b5730dea 100644
--- a/scripts/mso-agent-tool-router.mjs
+++ b/scripts/mso-agent-tool-router.mjs
@@ -10,6 +10,7 @@ const DEPENDENCIES = new Map([
["project_function_call", ["project_capabilities"]],
["exec_job_start", ["exec_job_status", "exec_job_cancel"]],
["fs_write", ["fs_read"]],
+ ["project_memory_upsert", ["project_memory_search"]],
["agent_session_resume", ["agent_sessions_list"]],
["local_agent_message_send", ["local_agents_list", "local_agent_inbox", "local_agent_reply"]],
["local_agent_reply", ["local_agent_inbox", "local_agents_list"]],
@@ -106,6 +107,10 @@ export function selectToolsForTurn(allTools = [], history = [], skillContext = n
for (const name of CORE_TOOL_NAMES) add(name);
for (const name of previousToolNames(history)) add(name);
for (const name of referencedTools(allTools, text)) add(name);
+ if (["test", "tested", "testing", "debug", "freeze", "freezes", "frozen", "crash", "crashed", "regression", "failed", "failure"].some((term) => queryWords.has(term))) {
+ add("project_memory_upsert");
+ add("project_memory_search");
+ }
const ranked = allTools
.map((tool) => ({ tool, score: score(tool, queryWords, text.toLowerCase()) }))
diff --git a/scripts/mso-agent-tool-router.test.ts b/scripts/mso-agent-tool-router.test.ts
index 7b4bd9bd..26fceaa7 100644
--- a/scripts/mso-agent-tool-router.test.ts
+++ b/scripts/mso-agent-tool-router.test.ts
@@ -10,6 +10,8 @@ const catalog = [
tool("sys_stats", "Live VPS CPU memory disk uptime health"), tool("sys_processes", "Top CPU processes"),
tool("apps_list", "Managed apps hermes openclaw"), tool("apps_logs", "Recent application logs"),
tool("fs_read", "Read a text file"), tool("fs_write", "Write or update a text file"),
+ tool("project_memory_search", "Search repo-local task debug test decision failure memory"),
+ tool("project_memory_upsert", "Persist repo-local memory including user manual tests"),
tool("exec_run", "Run a short shell command"), tool("exec_job_start", "Run long tests and builds"),
tool("exec_job_status", "Read long job status"), tool("exec_job_cancel", "Cancel long job"),
tool("screen_capture", "Capture screenshot"), tool("browser_status", "Camoufox browser state"),
@@ -83,4 +85,10 @@ describe("MSO per-turn tool router", () => {
expect(out.selectedNames).toContain("exec_job_status");
expect(out.selectedNames).toContain("exec_job_cancel");
});
+ it("loads repo memory tools when the user reports a manual regression", () => {
+ const out = selectToolsForTurn(catalog, [{ role: "user", text: "I tested it and it still freezes after reconnect" }]);
+ expect(out.selectedNames).toContain("project_memory_upsert");
+ expect(out.selectedNames).toContain("project_memory_search");
+ });
+
});