@jstn-sdk/ma 0.14.0 → 0.14.1

package/skills/maestro/SKILL.md

@@ -7,7 +7,7 @@ description: "Use when the user wants the singular Meta-Architect in-session aut
 
 ## Overview
 
-Use this skill inside Codex as the singular Meta-Architect umbrella surface and bounded autonomous manager. It inspects workflow state, chooses the smallest safe next step, manages the fixed gated design-and-review sequence one lane at a time, and routes helper handoffs when they are enough. There is no separate shipped `$meta-architect` skill.
+Use this skill inside Codex as the singular Meta-Architect umbrella surface and persistent autonomous manager. It accepts one task or a durable batch, inspects workflow state, chooses the smallest safe next step, manages the fixed gated design-and-review sequence, and keeps resuming eligible work until each task is completed, blocked, cancelled, or failed. It never invents a second umbrella command. There is no separate shipped `$meta-architect` skill.
 
 ## Workflow
 
@@ -30,6 +30,19 @@ Use this skill inside Codex as the singular Meta-Architect umbrella surface and
    - `$build`
 5. End with a clear result shape: decision, evidence, blockers, the lane assignment if any, and the exact next trigger.
 
+## Autonomous task loop
+
+For a task or batch, keep the manager loop active across turns:
+
+1. Normalize the request into the durable `.ma` task contract before dispatch.
+2. Discover the selected host, available skills, and required lane syntax without taking ownership of user-installed assets.
+3. Dispatch independent tasks with bounded concurrency and preserve dependency order for dependent tasks.
+4. Inspect, implement, test, review, repair, and verify. Route a failure back to its owning lane with the failure evidence attached.
+5. Persist checkpoints, receipts, and the next trigger after every transition so an interrupted process can resume safely.
+6. Continue unaffected batch tasks when one task is blocked, then return a batch summary with terminal states and unresolved blockers.
+
+Routine local work continues without asking for another prompt. Stop only for credentials, destructive actions, production or external mutations, explicit approval gates, unsafe commands, unavailable required providers, or missing verification evidence.
+
 ## Output
 
 Produce:
@@ -43,6 +56,9 @@ Produce:
 ## Rules
 
 - Prefer the smallest next step that moves the workflow forward safely.
+- Continue eligible work until the current task or batch reaches a terminal state; do not stop after a single successful lane.
+- Treat persisted `.ma` state as the source for resume, deduplication, dependency ordering, cancellation, and bounded retries.
+- Keep autonomous execution bounded by task dependencies, concurrency limits, deadlines, retry limits, and explicit safety gates.
 - Respect current gate state before recommending implementation or release work.
 - Be explicit when more evidence, planning, or validation is still needed.
 - Treat the in-session skill flow as primary. Use `ma ...` terminal helpers only when repo-local setup, inspection, or scripted state automation is explicitly the better support path.

package/skills/maestro/references/core-release-rules.md

@@ -8,6 +8,6 @@
   - `logic_status = GREEN`
   - `security_status = GREEN`
   - `experience_status = GREEN` or `WAIVED`
-- Feature work merges into `development`, never directly into `prod`.
-- Release promotion is allowed only from `development` or approved `release/*`.
+- Feature work merges into `dev`, never directly into `main`.
+- Release promotion is allowed only from `dev` or approved `release/*`.
 - Use the helper command path only when repo-local state automation is explicitly needed; otherwise stay inside Codex and carry the gate decisions in the session.

package/sprint/07-release.md

@@ -16,8 +16,8 @@ Move from completed bounded implementation to a controlled merge and release pat
 
 ## Exit criteria
 
-- merge follows `feature/* -> development`
-- release follows `development|release/* -> prod`
+- merge follows `feature/* -> dev`
+- release follows `dev|release/* -> main`
 
 ## Failure conditions
 

package/src/agents.js

@@ -1,5 +1,5 @@
-import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { safeSpawnSync } from "./process-utils.js";
 
 const definitions = {
   codex: {
@@ -240,11 +240,13 @@ export function detectInstalled(type = process.env.MA_AGENT || "codex") {
     };
   }
   const script = [".js", ".mjs", ".cjs"].includes(path.extname(command));
-  const result = spawnSync(
+  const result = safeSpawnSync(
     script ? process.execPath : command,
     script ? [command, "--version"] : ["--version"],
     {
       encoding: "utf8",
+      shell: false,
+      timeout: 5_000,
     },
   );
   return {

package/src/bootstrap.js

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -12,8 +11,10 @@ import {
 } from "./mcp-config.js";
 import { getMcpBridgeConfiguration, mcpClientVersion } from "./mcp-live-client.js";
 import { getMcpRootPath, getRepoRoot, getRuntimeWritePath, packageRoot } from "./paths.js";
+import { safeSpawnSync } from "./process-utils.js";
 import { resolveReleaseIssueGates } from "./release-issue-gates.js";
 import { loadReleaseState } from "./release-state.js";
+import { validateAgentIntegrations } from "./runtime/agent-compat.js";
 import { getArchitectReviewConfiguration } from "./runtime/architect-review.js";
 import { printDoctorStatuses, summarizeDoctorStatuses } from "./runtime/doctor-report.js";
 import { mcpWriteCapabilityStatus } from "./runtime/mcp-authority.js";
@@ -238,7 +239,7 @@ function inspectAgent(type = process.env.MA_AGENT || "codex") {
 }
 
 function listCodexPaths() {
-  const result = spawnSync("which", ["-a", "codex"], { encoding: "utf8" });
+  const result = safeSpawnSync("which", ["-a", "codex"], { encoding: "utf8" });
   if (result.error || result.status !== 0) {
     return [];
   }
@@ -599,6 +600,23 @@ async function runEnvironmentFlow({ fix, initMcp }) {
   statuses.push(await inspectLocalCapabilityState({ fix }));
   statuses.push(...(await inspectContextHealth()));
   statuses.push(await inspectPluginInjectionState());
+  if (agent.id === "cursor") {
+    try {
+      const validation = await validateAgentIntegrations(getRepoRoot(), { targets: ["cursor"] });
+      const cursorResult = validation.results.cursor;
+      statuses.push(
+        makeStatus(
+          cursorResult?.status === "valid" ? "OK" : "WARN",
+          "Cursor native project rules",
+          cursorResult?.status === "valid"
+            ? ".cursor/rules/agents.mdc validated"
+            : cursorResult?.issues?.map((issue) => issue.message).join(", ") || "run `ma setup`",
+        ),
+      );
+    } catch (error) {
+      statuses.push(makeStatus("WARN", "Cursor native project rules", error.message));
+    }
+  }
   return statuses;
 }
 

package/src/codex-app-server.js

@@ -1,5 +1,5 @@
-import { spawn } from "node:child_process";
 import fs from "node:fs";
+import { safeSpawn } from "./process-utils.js";
 
 const PACKAGE_VERSION = JSON.parse(
   fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -144,7 +144,7 @@ export class CodexAppServerClient {
 }
 
 export function createStdioTransport(command = "codex") {
-  const child = spawn(command, ["app-server", "--stdio"], {
+  const child = safeSpawn(command, ["app-server", "--stdio"], {
     stdio: ["pipe", "pipe", "inherit"],
     shell: false,
   });
@@ -205,7 +205,7 @@ export function runCodexExec({
 } = {}) {
   if (typeof prompt !== "string" || !prompt.trim()) throw new Error("Codex exec requires a prompt");
   return new Promise((resolve, reject) => {
-    const child = spawn(command, ["exec", "--json", ...args, prompt], {
+    const child = safeSpawn(command, ["exec", "--json", ...args, prompt], {
       cwd,
       stdio: ["ignore", "pipe", "pipe"],
       shell: false,
@@ -250,7 +250,7 @@ export function generateCodexBindings({
   if (!outDir) throw new Error("Codex binding generation requires an output directory");
   const generator = kind === "json-schema" ? "generate-json-schema" : "generate-ts";
   return new Promise((resolve, reject) => {
-    const child = spawn(command, ["app-server", generator, "--out", outDir], {
+    const child = safeSpawn(command, ["app-server", generator, "--out", outDir], {
       cwd,
       stdio: ["ignore", "pipe", "pipe"],
       shell: false,

package/src/launcher.js

@@ -1,6 +1,6 @@
-import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { getAgent, resolveAgentCommand } from "./agents.js";
+import { safeSpawnSync } from "./process-utils.js";
 
 const nativeCommands = new Set([
   "bootstrap",
@@ -46,7 +46,7 @@ export function runAgent(args, agentType = process.env.MA_AGENT || "codex") {
     : agentArgs;
   const command = commandArgs[0] === agentCommand ? process.execPath : agentCommand;
   const finalArgs = command === process.execPath ? commandArgs : agentArgs;
-  const result = spawnSync(command, finalArgs, { stdio: "inherit" });
+  const result = safeSpawnSync(command, finalArgs, { stdio: "inherit" });
 
   if (result.error) {
     if (result.error.code === "ENOENT") {

package/src/mcp-live-client.js

@@ -1,7 +1,7 @@
-import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { safeSpawn } from "./process-utils.js";
 import { maskSensitiveText } from "./runtime/redaction-gateway.js";
 
 const packageMetadata = JSON.parse(
@@ -63,7 +63,7 @@ export function createMcpLiveClient(endpoint) {
     return new McpStdioBridgeClient(
       endpoint,
       process.env[BRIDGE_COMMAND_ENV],
-      spawn,
+      safeSpawn,
       getMcpBridgeConfiguration(),
     );
   }

package/src/prelaunch.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { stdin as input, stdout as output } from "node:process";
 import readline from "node:readline/promises";
+import { Agents } from "@jstn-sdk/agents";
 import { agentRegistry, detectInstalled, listAgents } from "./agents.js";
 import {
   createSkillCompatibilityPayload,
@@ -159,6 +160,38 @@ export async function installPrelaunchSelection(selection, cwd = process.cwd())
     capabilities: ["maestro", "agent-compatibility"],
   });
   const results = [];
+  if (selection.scope === "project" && selection.targets.includes("cursor")) {
+    results.push(await ensureSkillsInstalled({ targetRoot: path.join(cwd, ".agents", "skills") }));
+    results.push(
+      await Agents.compile(
+        {
+          version: 1,
+          project: { name: path.basename(path.resolve(cwd)) },
+          instructions: [
+            "Use Meta-Architect lanes for architecture, evidence, review, and gated build work.",
+            "Run `ma run '$maestro'` when the host supports shell execution, or invoke /maestro in Cursor Agent.",
+          ],
+        },
+        { targets: ["cursor"], output: cwd },
+      ),
+    );
+  }
+  if (selection.scope === "project" && selection.targets.includes("claude-code")) {
+    results.push(await ensureSkillsInstalled({ targetRoot: path.join(cwd, ".claude", "skills") }));
+    results.push(
+      await Agents.compile(
+        {
+          version: 1,
+          project: { name: path.basename(path.resolve(cwd)) },
+          instructions: [
+            "Use Meta-Architect lanes for architecture, evidence, review, and gated build work.",
+            "Invoke /maestro to run the autonomous Meta-Architect manager in Claude Code.",
+          ],
+        },
+        { targets: ["claude-code"], output: cwd },
+      ),
+    );
+  }
   if (selection.targets.includes("codex")) {
     const skillsRoot =
       selection.scope === "global" ? undefined : path.join(cwd, ".agents", "skills");
@@ -175,6 +208,7 @@ export async function installPrelaunchSelection(selection, cwd = process.cwd())
       await writeSkillCompatibilityExport({
         payload,
         agentType: target,
+        renderAgentType: selection.targets.length > 1 ? "generic" : target,
         cwd,
         global: selection.scope === "global",
         agentRootExists: true,

package/src/process-utils.js

@@ -0,0 +1,62 @@
+import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
+import { promisify } from "node:util";
+
+const unsafeExecutable = /[;&|<>`$]/;
+
+export function assertSafeExecutable(command, label = "Executable") {
+  if (
+    typeof command !== "string" ||
+    command.trim() === "" ||
+    command !== command.trim() ||
+    command.includes("\0") ||
+    command.includes("\r") ||
+    command.includes("\n") ||
+    unsafeExecutable.test(command)
+  ) {
+    throw new Error(`${label} contains an unsafe executable value`);
+  }
+  return command;
+}
+
+function assertArgs(args) {
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || arg.includes("\0")))
+    throw new Error("Process arguments must be an array of strings without NUL bytes");
+}
+
+function safeOptions(options = {}) {
+  return { ...options, shell: false };
+}
+
+export function safeSpawn(command, args = [], options = {}) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return spawn(command, args, safeOptions(options));
+}
+
+export function safeSpawnSync(command, args = [], options = {}) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return spawnSync(command, args, safeOptions(options));
+}
+
+export function safeExecFile(command, args = [], options = {}, callback) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  if (typeof options === "function") {
+    callback = options;
+    options = {};
+  }
+  return execFile(command, args, safeOptions(options), callback);
+}
+
+export function safeExecFileSync(command, args = [], options = {}) {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return execFileSync(command, args, safeOptions(options));
+}
+
+safeExecFile[promisify.custom] = (command, args = [], options = {}) => {
+  assertSafeExecutable(command);
+  assertArgs(args);
+  return promisify(execFile)(command, args, safeOptions(options));
+};

package/src/quality/ai-quality-orchestrator.js

@@ -1,9 +1,9 @@
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { writeJson } from "../fs-utils.js";
 import { packageRoot } from "../paths.js";
+import { safeSpawn } from "../process-utils.js";
 
 const QUALITY_ROOT = path.join(".ma", "quality");
 let appendQueue = Promise.resolve();
@@ -94,7 +94,7 @@ function calculateQualityScore(kpis) {
 
 function runCommand(command, args, options = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+    const child = safeSpawn(command, args, {
       cwd: options.cwd,
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],

package/src/release-operations.js

@@ -1,7 +1,7 @@
-import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { safeExecFile } from "./process-utils.js";
 
-const execFileAsync = promisify(execFile);
+const execFileAsync = promisify(safeExecFile);
 const branchPattern = /^[A-Za-z0-9._/-]+$/;
 
 function assertBranch(value, label) {
@@ -26,11 +26,20 @@ export async function inspectGitOperation(root, sourceBranch, targetBranch) {
   const operation = getGitOperation(sourceBranch, targetBranch);
   try {
     const [branch, status] = await Promise.all([
-      execFileAsync("git", ["branch", "--show-current"], { cwd: root, encoding: "utf8" }),
-      execFileAsync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf8" }),
+      execFileAsync("git", ["branch", "--show-current"], {
+        cwd: root,
+        encoding: "utf8",
+        timeout: 10_000,
+      }),
+      execFileAsync("git", ["status", "--porcelain"], {
+        cwd: root,
+        encoding: "utf8",
+        timeout: 10_000,
+      }),
       execFileAsync("git", ["rev-parse", "--verify", `refs/heads/${sourceBranch}`], {
         cwd: root,
         encoding: "utf8",
+        timeout: 10_000,
       }),
     ]);
     return {
@@ -57,6 +66,7 @@ export async function executeGitOperation(root, operation) {
   const result = await execFileAsync(operation.command, operation.args, {
     cwd: root,
     encoding: "utf8",
+    timeout: 30_000,
   });
   return { ...operation, stdout: result.stdout.trim(), stderr: result.stderr.trim() };
 }

package/src/runtime/architect-review.js

@@ -1,9 +1,9 @@
-import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
 import { getRuntimeStatePath } from "../paths.js";
+import { safeSpawnSync } from "../process-utils.js";
 import {
   maskSensitiveText,
   redactProviderBoundPayload,
@@ -74,7 +74,7 @@ export async function runExternalArchitectReview({ prompt = "" } = {}) {
     getArchitectReviewConfiguration(),
   );
   const timeout = readReviewTimeoutMs();
-  const result = spawnSync(binary, args, {
+  const result = safeSpawnSync(binary, args, {
     cwd: process.cwd(),
     env: buildArchitectReviewEnv({
       MA_ARCHITECT_REVIEW_PROMPT: redactedPrompt.sanitizedText,