opencode-magi 0.4.0 → 0.5.0

package/README.md

@@ -61,26 +61,33 @@ Add the following content to the configuration file.
 ```json
 {
   "$schema": "https://raw.githubusercontent.com/magi-ai/opencode-magi/main/schema.json",
-  "review": {
-    "agents": [
-      {
-        "account": "your-account-1",
-        "model": "openai/gpt-5.5"
+  "agents": {
+    "refs": {
+      "account-1": {
+        "model": "openai/gpt-5.5",
+        "account": "account-1"
       },
-      {
-        "account": "your-account-2",
-        "model": "anthropic/claude-opus-4-7"
+      "account-2": {
+        "model": "anthropic/claude-opus-4-7",
+        "account": "account-2"
       },
-      {
-        "account": "your-account-3",
-        "model": "opencode/kimi-k2-6"
+      "account-3": {
+        "model": "opencode/kimi-k2-6",
+        "account": "account-3"
       }
+    }
+  },
+  "review": {
+    "agents": [
+      { "ref": "account-1" },
+      { "ref": "account-2" },
+      { "ref": "account-3" }
     ]
   }
 }
 ```
 
-`review.agents[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique.
+After refs are expanded, `review.agents[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique.
 
 #### Set project config
 
@@ -101,53 +108,54 @@ Add the following content to the configuration file.
     "owner": "your-owner",
     "repo": "your-repo"
   },
-  "review": {
-    "agents": [
-      {
-        "account": "your-account-1",
-        "model": "openai/gpt-5.5"
+  "agents": {
+    "refs": {
+      "account-1": {
+        "model": "openai/gpt-5.5",
+        "account": "account-1"
       },
-      {
-        "account": "your-account-2",
-        "model": "anthropic/claude-opus-4-7"
+      "account-2": {
+        "model": "anthropic/claude-opus-4-7",
+        "account": "account-2"
       },
-      {
-        "account": "your-account-3",
-        "model": "opencode/kimi-k2-6"
+      "account-3": {
+        "model": "opencode/kimi-k2-6",
+        "account": "account-3"
+      },
+      "account-4": {
+        "model": "openai/gpt-5.5",
+        "account": "account-4",
+        "author": {
+          "name": "account-4",
+          "email": "your-email@example.com"
+        }
       }
+    }
+  },
+  "review": {
+    "agents": [
+      { "ref": "account-1" },
+      { "ref": "account-2" },
+      { "ref": "account-3" }
     ]
   },
   "merge": {
-    "editor": {
-      "account": "your-editor-account",
-      "model": "openai/gpt-5.5",
-      "author": {
-        "name": "your-account",
-        "email": "your-email@example.com"
-      }
-    }
+    "editor": { "ref": "account-4" }
   },
   "triage": {
-    "account": "your-triage-account",
+    "account": "account-5",
     "agents": [
-      {
-        "id": "general",
-        "model": "openai/gpt-5.5"
-      },
-      {
-        "id": "maintenance",
-        "model": "anthropic/claude-opus-4-7"
-      },
-      {
-        "id": "product",
-        "model": "opencode/kimi-k2-6"
-      }
+      { "ref": "account-1" },
+      { "ref": "account-2" },
+      { "ref": "account-3" }
     ]
   }
 }
 ```
 
-`review.agents[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique. `merge.editor.account` is used by `/magi:merge` to push fixes, close PRs, and merge PRs.
+Entries with `ref` are expanded from `agents.refs`. Fields set alongside `ref` override fields from the preset.
+
+After refs are expanded, `review.agents[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique. `merge.editor.account` is used by `/magi:merge` to push fixes, close PRs, and merge PRs.
 
 #### Validate config
 

package/dist/github/commands.js

@@ -246,6 +246,12 @@ function duplicateReferences(text) {
         refs.add(Number(match[1]));
     return [...refs];
 }
+function issueTitleSearchQuery(title, fallback) {
+    return (title
+        .replaceAll(/[^\p{L}\p{N}_]+/gu, " ")
+        .replaceAll(/\s+/g, " ")
+        .trim() || fallback);
+}
 async function fetchIssueCandidate(exec, repository, number, whyCandidate) {
     const raw = await exec(`gh issue view ${number} --repo ${shellQuote(repoSpecifier(repository))} --json number,title,url,state,body,createdAt`).catch(() => undefined);
     if (!raw)
@@ -254,7 +260,7 @@ async function fetchIssueCandidate(exec, repository, number, whyCandidate) {
     return { ...data, whyCandidate };
 }
 export async function searchDuplicateIssues(exec, repository, issue, limit = 5) {
-    const query = issue.title;
+    const query = issueTitleSearchQuery(issue.title, String(issue.number));
     const explicitCandidates = await Promise.all(duplicateReferences(issue.body)
         .filter((number) => number !== issue.number)
         .map((number) => fetchIssueCandidate(exec, repository, number, "Issue body explicitly references a duplicate target.")));
@@ -509,9 +515,6 @@ export async function postCloseComment(exec, repository, pr, account, body) {
         await rm(payloadPath, { force: true });
     }
 }
-function isInlineFinding(finding) {
-    return finding.line != null;
-}
 function findingComment(finding) {
     const comment = {
         body: `**Issue:** ${finding.issue}\n\n**Fix:** ${finding.fix}`,
@@ -525,54 +528,18 @@ function findingComment(finding) {
     }
     return comment;
 }
-function requirementFindingSummary(finding) {
-    return [
-        `- Missing issue #${finding.issueNumber} requirement: ${finding.requirement}`,
-        `  Evidence: ${finding.evidence}`,
-        `  Fix: ${finding.fix}`,
-    ].join("\n");
-}
-function findingLocation(finding) {
-    if (finding.line == null)
-        return finding.path;
-    if (finding.startLine == null)
-        return `${finding.path}:${finding.line}`;
-    return `${finding.path}:${finding.startLine}-${finding.line}`;
-}
-function findingSummary(finding) {
-    return [
-        `- ${findingLocation(finding)}: ${finding.issue}`,
-        `  Fix: ${finding.fix}`,
-    ]
-        .filter(Boolean)
-        .join("\n");
-}
-function changesRequestedBody(findings, requirementFindings) {
-    const inlineFindings = findings.filter(isInlineFinding);
-    const fileLevelFindings = findings.filter((finding) => !isInlineFinding(finding));
-    const sections = [];
-    if (inlineFindings.length) {
-        sections.push(["Inline findings:", ...inlineFindings.map(findingSummary)].join("\n"));
-    }
-    if (fileLevelFindings.length) {
-        sections.push(["File-level findings:", ...fileLevelFindings.map(findingSummary)].join("\n"));
-    }
-    if (requirementFindings.length) {
-        sections.push([
-            "Requirement findings:",
-            ...requirementFindings.map(requirementFindingSummary),
-        ].join("\n"));
-    }
-    return sections.join("\n\n");
+function changesRequestedBody(findings) {
+    return findings.length === 1
+        ? "Changes requested: 1 inline comment."
+        : `Changes requested: ${findings.length} inline comments.`;
 }
-export async function postChangesRequested(exec, repository, pr, account, findings, requirementFindings = []) {
+export async function postChangesRequested(exec, repository, pr, account, findings) {
     const token = await ghToken(exec, repository, account);
     const payloadPath = join(tmpdir(), `magi-review-${process.pid}-${Date.now()}.json`);
-    const inlineFindings = findings.filter(isInlineFinding);
-    const body = changesRequestedBody(findings, requirementFindings);
+    const body = changesRequestedBody(findings);
     await writeFile(payloadPath, JSON.stringify({
         body,
-        comments: inlineFindings.map(findingComment),
+        comments: findings.map(findingComment),
         event: "REQUEST_CHANGES",
     }));
     try {

package/dist/index.js

@@ -95,12 +95,17 @@ export function parseRunArguments(value, dryRun = false, command = "review") {
     const tokens = value.split(/[\s,]+/).filter(Boolean);
     const configOverrides = {};
     const prTokens = [];
+    let sync = false;
     for (let index = 0; index < tokens.length; index++) {
         const token = tokens[index];
         if (token === "--dry-run") {
             dryRun = true;
             continue;
         }
+        if (token === "--sync") {
+            sync = true;
+            continue;
+        }
         switch (token) {
             case "--language":
                 setConfigOverride(configOverrides, ["language"], nextFlagValue(tokens, ++index, token));
@@ -146,18 +151,23 @@ export function parseRunArguments(value, dryRun = false, command = "review") {
                 prTokens.push(token);
         }
     }
-    return { configOverrides, dryRun, prs: parsePrs(prTokens.join(" ")) };
+    return { configOverrides, dryRun, prs: parsePrs(prTokens.join(" ")), sync };
 }
 export function parseIssueRunArguments(value, dryRun = false) {
     const tokens = value.split(/[\s,]+/).filter(Boolean);
     const configOverrides = {};
     const issueTokens = [];
+    let sync = false;
     for (let index = 0; index < tokens.length; index++) {
         const token = tokens[index];
         if (token === "--dry-run") {
             dryRun = true;
             continue;
         }
+        if (token === "--sync") {
+            sync = true;
+            continue;
+        }
         switch (token) {
             case "--language":
                 setConfigOverride(configOverrides, ["language"], nextFlagValue(tokens, ++index, token));
@@ -195,7 +205,12 @@ export function parseIssueRunArguments(value, dryRun = false) {
                 issueTokens.push(token);
         }
     }
-    return { configOverrides, dryRun, issues: parseIssues(issueTokens.join(" ")) };
+    return {
+        configOverrides,
+        dryRun,
+        issues: parseIssues(issueTokens.join(" ")),
+        sync,
+    };
 }
 function nextFlagValue(tokens, index, flag) {
     const value = tokens[index];
@@ -203,6 +218,15 @@ function nextFlagValue(tokens, index, flag) {
         throw new Error(`${flag} requires a value.`);
     return value;
 }
+async function syncResult(runManager, states) {
+    const output = await runManager.formatStatesWithReports(states, {
+        verbose: true,
+    });
+    const failed = states.filter((state) => state.status !== "completed");
+    if (failed.length)
+        throw new Error(output);
+    return output;
+}
 function parseIntegerFlag(value, flag, minimum) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isInteger(parsed) ||
@@ -432,6 +456,7 @@ export const MagiPlugin = async ({ client, directory }) => {
                 args: {
                     prs: tool.schema.string(),
                     dryRun: tool.schema.boolean().optional(),
+                    sync: tool.schema.boolean().optional(),
                 },
                 async execute(args, context) {
                     const parsed = parseRunArguments(args.prs, args.dryRun ?? false, "merge");
@@ -448,6 +473,7 @@ export const MagiPlugin = async ({ client, directory }) => {
                     if (!validation.ok)
                         return JSON.stringify(validation, null, 2);
                     const repository = resolveRepository(config);
+                    const sync = parsed.sync || args.sync === true;
                     const states = await mapPool(parsed.prs, repository.concurrency.runs, (pr) => runManager.startMerge({
                         config,
                         dryRun: parsed.dryRun,
@@ -455,7 +481,10 @@ export const MagiPlugin = async ({ client, directory }) => {
                         pr,
                         parentSessionId: context.sessionID,
                         signal: context.abort,
+                        sync,
                     }), { signal: context.abort });
+                    if (sync)
+                        return syncResult(runManager, states);
                     return states
                         .map((state) => `Started reviewing ${prMarkdownLink(repository, state.pr)}.`)
                         .join("\n");
@@ -469,6 +498,7 @@ export const MagiPlugin = async ({ client, directory }) => {
                 args: {
                     prs: tool.schema.string(),
                     dryRun: tool.schema.boolean().optional(),
+                    sync: tool.schema.boolean().optional(),
                 },
                 async execute(args, context) {
                     const parsed = parseRunArguments(args.prs, args.dryRun ?? false);
@@ -484,6 +514,7 @@ export const MagiPlugin = async ({ client, directory }) => {
                     if (!validation.ok)
                         return JSON.stringify(validation, null, 2);
                     const repository = resolveRepository(config);
+                    const sync = parsed.sync || args.sync === true;
                     const states = await mapPool(parsed.prs, repository.concurrency.runs, (pr) => runManager.startReview({
                         config,
                         dryRun: parsed.dryRun,
@@ -491,7 +522,10 @@ export const MagiPlugin = async ({ client, directory }) => {
                         pr,
                         parentSessionId: context.sessionID,
                         signal: context.abort,
+                        sync,
                     }), { signal: context.abort });
+                    if (sync)
+                        return syncResult(runManager, states);
                     return states
                         .map((state) => `Started reviewing ${prMarkdownLink(repository, state.pr)}.`)
                         .join("\n");
@@ -502,6 +536,7 @@ export const MagiPlugin = async ({ client, directory }) => {
                 args: {
                     issues: tool.schema.string(),
                     dryRun: tool.schema.boolean().optional(),
+                    sync: tool.schema.boolean().optional(),
                 },
                 async execute(args, context) {
                     const parsed = parseIssueRunArguments(args.issues, args.dryRun ?? false);
@@ -523,6 +558,7 @@ export const MagiPlugin = async ({ client, directory }) => {
                     const repository = resolveRepository(config);
                     if (!repository.triage)
                         return JSON.stringify({ errors: ["triage configuration is required"], ok: false }, null, 2);
+                    const sync = parsed.sync || args.sync === true;
                     const states = await mapPool(parsed.issues, repository.triage.concurrency.runs, (issue) => runManager.startTriage({
                         config,
                         dryRun: parsed.dryRun,
@@ -530,7 +566,10 @@ export const MagiPlugin = async ({ client, directory }) => {
                         parentSessionId: context.sessionID,
                         repository,
                         signal: context.abort,
+                        sync,
                     }), { signal: context.abort });
+                    if (sync)
+                        return syncResult(runManager, states);
                     return states
                         .map((state) => `Started triaging ${issueMarkdownLink(repository, state.issue)}.`)
                         .join("\n");

package/dist/orchestrator/findings.js

@@ -58,10 +58,9 @@ export function applyFindingValidation(input) {
             discarded.push(target);
             return false;
         });
-        next[reviewer] =
-            findings.length || output.requirementFindings.length
-                ? { ...output, findings }
-                : { findings: [], requirementFindings: [], verdict: "MERGE" };
+        next[reviewer] = findings.length
+            ? { ...output, findings }
+            : { findings: [], verdict: "MERGE" };
     }
     return { outputs: next, summary: { discarded, kept } };
 }

package/dist/orchestrator/inline-comments.js

@@ -52,12 +52,6 @@ function assertPositiveInteger(value, name) {
 export function validateInlineCommentTargets(findings, targets, label = "findings") {
     for (const [index, finding] of findings.entries()) {
         const name = `${label}[${index}]`;
-        if (finding.line == null) {
-            if (finding.startLine != null) {
-                throw new Error(`${name}.startLine requires line`);
-            }
-            continue;
-        }
         assertPositiveInteger(finding.line, `${name}.line`);
         if (finding.startLine != null) {
             assertPositiveInteger(finding.startLine, `${name}.startLine`);

package/dist/orchestrator/merge.js

@@ -146,14 +146,14 @@ async function postRereviewOutput(input, reviewerKey, output) {
     if (output.verdict === "CLOSE") {
         return postCloseComment(input.exec, input.repository, input.pr, reviewer.account, output.reason ?? "Close requested.");
     }
-    if (output.newFindings.length || output.requirementFindings.length) {
+    if (output.newFindings.length) {
         return postChangesRequested(input.exec, input.repository, input.pr, reviewer.account, output.newFindings.map((finding) => ({
             fix: "Please address this before merging.",
             issue: finding.body,
             path: finding.path,
-            ...(finding.line == null ? {} : { line: finding.line }),
+            line: finding.line,
             startLine: finding.startLine,
-        })), output.requirementFindings);
+        })));
     }
     return replies[0] ?? "";
 }
@@ -166,45 +166,29 @@ function newFindingToEditorFinding(reviewer, finding) {
     return {
         body: finding.body,
         fix: "Please address this before merging.",
+        line: finding.line,
         path: finding.path,
         reviewer,
-        ...(finding.line == null ? {} : { line: finding.line }),
         ...(finding.startLine == null ? {} : { startLine: finding.startLine }),
-        type: finding.line == null ? "file" : "inline",
+        type: "inline",
     };
 }
 export function blockingReviewFindings(outputs) {
     return Object.entries(outputs).flatMap(([reviewer, output]) => {
         if (output.verdict !== "CHANGES_REQUESTED")
             return [];
-        const requirementFindings = output.requirementFindings.map((finding) => ({
-            evidence: finding.evidence,
-            fix: finding.fix,
-            issueNumber: finding.issueNumber,
-            requirement: finding.requirement,
-            reviewer,
-            type: "requirement",
-        }));
         if ("findings" in output) {
-            return [
-                ...output.findings.map((finding) => ({
-                    fix: finding.fix,
-                    issue: finding.issue,
-                    path: finding.path,
-                    reviewer,
-                    ...(finding.line == null ? {} : { line: finding.line }),
-                    ...(finding.startLine == null
-                        ? {}
-                        : { startLine: finding.startLine }),
-                    type: finding.line == null ? "file" : "inline",
-                })),
-                ...requirementFindings,
-            ];
+            return output.findings.map((finding) => ({
+                fix: finding.fix,
+                issue: finding.issue,
+                line: finding.line,
+                path: finding.path,
+                reviewer,
+                ...(finding.startLine == null ? {} : { startLine: finding.startLine }),
+                type: "inline",
+            }));
         }
-        return [
-            ...output.newFindings.map((finding) => newFindingToEditorFinding(reviewer, finding)),
-            ...requirementFindings,
-        ];
+        return output.newFindings.map((finding) => newFindingToEditorFinding(reviewer, finding));
     });
 }
 async function runRereview(input, worktreePath, previousHeadSha, cycle, sessionIds, ciFailureContext, options = {}) {
@@ -507,8 +491,6 @@ function syntheticReviewThreads(outputs) {
     for (const [reviewer, output] of Object.entries(outputs)) {
         if ("findings" in output) {
             threads[reviewer] = output.findings.flatMap((finding) => {
-                if (finding.line == null)
-                    return [];
                 const commentId = nextCommentId--;
                 return [
                     {
@@ -531,8 +513,6 @@ function syntheticReviewThreads(outputs) {
             continue;
         }
         threads[reviewer] = output.newFindings.flatMap((finding) => {
-            if (finding.line == null)
-                return [];
             const commentId = nextCommentId--;
             return [
                 {
@@ -721,9 +701,7 @@ export async function runMerge(input) {
                 threads: unresolvedThreads,
             });
             const editorFindings = blockingReviewFindings(reportOutputs);
-            const editableFindings = editableThreads.length
-                ? editorFindings
-                : editorFindings.filter((finding) => finding.type !== "inline");
+            const editableFindings = editableThreads.length ? editorFindings : [];
             const findingAttemptsExhausted = input.repository.merge.maxThreadResolutionCycles !== 0 &&
                 cycle > input.repository.merge.maxThreadResolutionCycles;
             if (!editableThreads.length &&

package/dist/orchestrator/report.js

@@ -16,24 +16,17 @@ function pullRequestLine(input) {
     return `- **Pull Request**: [#${input.pr}](${url})`;
 }
 function formatFinding(finding) {
-    const line = finding.line == null
-        ? finding.path
-        : finding.startLine == null
-            ? `${finding.path}:${finding.line}`
-            : `${finding.path}:${finding.startLine}-${finding.line}`;
+    const line = finding.startLine == null
+        ? `${finding.path}:${finding.line}`
+        : `${finding.path}:${finding.startLine}-${finding.line}`;
     return `\`${line}\`: ${finding.issue}`;
 }
 function formatRereviewFinding(finding) {
-    const line = finding.line == null
-        ? finding.path
-        : finding.startLine == null
-            ? `${finding.path}:${finding.line}`
-            : `${finding.path}:${finding.startLine}-${finding.line}`;
+    const line = finding.startLine == null
+        ? `${finding.path}:${finding.line}`
+        : `${finding.path}:${finding.startLine}-${finding.line}`;
     return `\`${line}\`: ${finding.body}`;
 }
-function formatRequirementFinding(finding) {
-    return `Issue #${finding.issueNumber}: ${finding.requirement}`;
-}
 function isReviewOutput(output) {
     return "findings" in output;
 }
@@ -85,10 +78,7 @@ function reviewerDetailLines(output) {
             return output.reason ? [output.reason] : [];
         if (output.verdict !== "CHANGES_REQUESTED")
             return [];
-        return [
-            ...output.findings.map(formatFinding),
-            ...output.requirementFindings.map(formatRequirementFinding),
-        ];
+        return output.findings.map(formatFinding);
     }
     if (output.verdict === "CLOSE")
         return output.reason ? [output.reason] : [];
@@ -96,7 +86,6 @@ function reviewerDetailLines(output) {
         return [];
     return [
         ...output.newFindings.map(formatRereviewFinding),
-        ...output.requirementFindings.map(formatRequirementFinding),
         ...output.followUps.map((item) => `Comment #${item.commentId}: ${item.body}`),
     ];
 }

package/dist/orchestrator/review-context.js

@@ -37,6 +37,23 @@ function quoteEvidence(value) {
     const compact = value.replaceAll(/\s+/g, " ").trim();
     return compact.length > 120 ? `${compact.slice(0, 117)}...` : compact;
 }
+function errorText(error) {
+    if (!error || typeof error !== "object")
+        return String(error);
+    const value = error;
+    return [value.message, value.stderr, value.stdout]
+        .filter((item) => typeof item === "string")
+        .join("\n");
+}
+function isIssueLookupFailure(error) {
+    const text = errorText(error);
+    return (/could not resolve to an issue/i.test(text) ||
+        /could not fetch issue #\d+/i.test(text) ||
+        /not an issue/i.test(text));
+}
+function isIssueUrl(url) {
+    return /\/issues\/\d+(?:$|[/?#])/i.test(url);
+}
 function issueReferencePattern(repository) {
     const host = escapeRegExp(repository.github.host || "github.com");
     const owner = escapeRegExp(repository.github.owner);
@@ -120,6 +137,9 @@ export function collectIssueRelationships(input) {
 async function contextIssue(input) {
     const issue = input.issue ??
         (await fetchIssue(input.exec, input.repository, input.relationship.number));
+    if (!isIssueUrl(issue.url)) {
+        throw new Error(`Reference #${issue.number} resolved to ${issue.url}, not an Issue`);
+    }
     const commentPage = await fetchIssueCommentPage(input.exec, input.repository, issue.number, input.limit);
     return {
         author: issue.author,
@@ -138,6 +158,19 @@ async function contextIssue(input) {
         url: issue.url,
     };
 }
+async function contextIssueIfIssue(input) {
+    try {
+        return await contextIssue(input);
+    }
+    catch (error) {
+        if (isIssueLookupFailure(error))
+            return undefined;
+        throw error;
+    }
+}
+function presentIssue(issue) {
+    return Boolean(issue);
+}
 function orderReviewThreads(threads) {
     return [...threads]
         .sort((a, b) => {
@@ -183,13 +216,13 @@ export async function buildReviewContextSnapshot(input) {
     const closingRelationships = relationships.filter((relationship) => relationship.relationship === "closing");
     const referencedRelationships = relationships.filter((relationship) => relationship.relationship === "referenced");
     return {
-        closingIssues: await Promise.all(closingRelationships.map((relationship) => contextIssue({
+        closingIssues: (await Promise.all(closingRelationships.map((relationship) => contextIssueIfIssue({
             exec: input.exec,
             issue: closingIssueMap.get(relationship.number),
             limit: LIMITS.closingIssueComments,
             relationship,
             repository: input.repository,
-        }))),
+        })))).filter(presentIssue),
         pullRequest: {
             author: input.pr.author?.login ?? safetyMeta.author,
             baseRef: input.pr.baseRefName,
@@ -207,12 +240,12 @@ export async function buildReviewContextSnapshot(input) {
             title: input.pr.title,
             url: input.pr.url,
         },
-        referencedIssues: await Promise.all(referencedRelationships.map((relationship) => contextIssue({
+        referencedIssues: (await Promise.all(referencedRelationships.map((relationship) => contextIssueIfIssue({
             exec: input.exec,
             limit: LIMITS.referencedIssueComments,
             relationship,
             repository: input.repository,
-        }))),
+        })))).filter(presentIssue),
         reviewDiscussion: {
             prComments: boundedComments(prComments, LIMITS.prComments),
             prCommentsOmitted,

package/dist/orchestrator/review.js

@@ -39,7 +39,7 @@ async function postReviewOutput(input, reviewerKey, output) {
         return postApproval(input.exec, input.repository, input.pr, reviewer.account);
     if (output.verdict === "CLOSE")
         return postCloseComment(input.exec, input.repository, input.pr, reviewer.account, output.reason ?? "Close requested.");
-    return postChangesRequested(input.exec, input.repository, input.pr, reviewer.account, output.findings, output.requirementFindings);
+    return postChangesRequested(input.exec, input.repository, input.pr, reviewer.account, output.findings);
 }
 function dryRunReviewPost(key, output) {
     if (output.verdict === "MERGE")
@@ -147,11 +147,10 @@ function parsePostedFindingLocation(location) {
     const line = /^(.*):(\d+)$/.exec(location);
     if (line)
         return { line: Number(line[2]), path: line[1] ?? location };
-    return { path: location };
+    return undefined;
 }
 function reviewFindingsFromBody(body) {
     const findings = [];
-    const requirementFindings = [];
     const lines = (body ?? "").split(/\r?\n/);
     let section;
     for (let index = 0; index < lines.length; index += 1) {
@@ -161,7 +160,7 @@ function reviewFindingsFromBody(body) {
             continue;
         }
         if (line === "Requirement findings:") {
-            section = "requirement";
+            section = undefined;
             continue;
         }
         if (section === "finding") {
@@ -169,30 +168,19 @@ function reviewFindingsFromBody(body) {
             const fix = /^\s+Fix: (.+)$/.exec(lines[index + 1] ?? "");
             if (!match || !fix)
                 continue;
+            const location = parsePostedFindingLocation(match[1] ?? "");
+            if (!location)
+                continue;
             findings.push({
-                ...parsePostedFindingLocation(match[1] ?? ""),
+                ...location,
                 fix: fix[1] ?? "Please address this before merging.",
                 issue: match[2] ?? "Review finding.",
             });
             index += 1;
             continue;
         }
-        if (section !== "requirement")
-            continue;
-        const match = /^- Missing issue #(\d+) requirement: (.+)$/.exec(line ?? "");
-        const evidence = /^\s+Evidence: (.+)$/.exec(lines[index + 1] ?? "");
-        const fix = /^\s+Fix: (.+)$/.exec(lines[index + 2] ?? "");
-        if (!match || !evidence || !fix)
-            continue;
-        requirementFindings.push({
-            evidence: evidence[1] ?? "See review body.",
-            fix: fix[1] ?? "Please address this before merging.",
-            issueNumber: Number(match[1]),
-            requirement: match[2] ?? "Review requirement.",
-        });
-        index += 2;
     }
-    return { findings, requirementFindings };
+    return { findings };
 }
 export function reviewOutputFromState(review) {
     const verdict = reviewStateToVerdict(review.state);
@@ -202,10 +190,9 @@ export function reviewOutputFromState(review) {
         ? {
             findings: [],
             reason: review.body || "Close requested.",
-            requirementFindings: [],
             verdict,
         }
-        : { findings: [], requirementFindings: [], verdict };
+        : { findings: [], verdict };
 }
 export function hasPendingThreadReply(threads, reviewerAccount) {
     return threads.some((thread) => {
@@ -229,15 +216,15 @@ async function postRereviewOutput(input, reviewerKey, output) {
         return postApproval(input.exec, input.repository, input.pr, reviewer.account);
     if (output.verdict === "CLOSE")
         return postCloseComment(input.exec, input.repository, input.pr, reviewer.account, output.reason ?? "Close requested.");
-    if (!output.newFindings.length && !output.requirementFindings.length)
+    if (!output.newFindings.length)
         return "";
     return postChangesRequested(input.exec, input.repository, input.pr, reviewer.account, output.newFindings.map((finding) => ({
         fix: "Please address this before merging.",
         issue: finding.body,
         path: finding.path,
-        ...(finding.line == null ? {} : { line: finding.line }),
+        line: finding.line,
         startLine: finding.startLine,
-    })), output.requirementFindings);
+    })));
 }
 function isReviewOutput(output) {
     return "findings" in output;

package/dist/orchestrator/run-manager.js

@@ -15,6 +15,7 @@ const DEFAULT_CLEAR_OPTIONS = {
     session: true,
     worktree: true,
 };
+const SYNC_RUN_TIMEOUT_MS = 600_000;
 function createRunId() {
     return `run-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
 }
@@ -453,11 +454,14 @@ export class MagiRunManager {
         await this.notify(state, `Started Magi review for ${prMarkdownLink(state)}.`);
         const controller = new AbortController();
         this.controllers.set(runId, controller);
-        void this.executeReview({
+        const execute = () => this.executeReview({
             ...input,
             runId,
             signal: controller.signal,
-        }).catch(async (error) => {
+        });
+        if (input.sync)
+            return this.executeSync(state, controller, execute);
+        void execute().catch(async (error) => {
             await this.failRun(runId, error);
         });
         return state;
@@ -511,11 +515,14 @@ export class MagiRunManager {
         await this.notify(state, `Started Magi merge for ${prMarkdownLink(state)}.`);
         const controller = new AbortController();
         this.controllers.set(runId, controller);
-        void this.executeMerge({
+        const execute = () => this.executeMerge({
             ...input,
             runId,
             signal: controller.signal,
-        }).catch(async (error) => {
+        });
+        if (input.sync)
+            return this.executeSync(state, controller, execute);
+        void execute().catch(async (error) => {
             await this.failRun(runId, error);
         });
         return state;
@@ -568,11 +575,14 @@ export class MagiRunManager {
         await this.notify(state, `Started Magi triage for ${issueMarkdownLink(state)}.`);
         const controller = new AbortController();
         this.controllers.set(runId, controller);
-        void this.executeTriage({
+        const execute = () => this.executeTriage({
             ...input,
             runId,
             signal: controller.signal,
-        }).catch(async (error) => {
+        });
+        if (input.sync)
+            return this.executeSync(state, controller, execute);
+        void execute().catch(async (error) => {
             await this.failRun(runId, error);
         });
         return state;
@@ -1210,6 +1220,36 @@ export class MagiRunManager {
     hasBlockedAgents(state) {
         return this.agentEntries(state).some(([, agent]) => agent.status === "blocked");
     }
+    async executeSync(state, controller, execute) {
+        let timeout;
+        const timeoutPromise = new Promise((resolve) => {
+            timeout = setTimeout(() => resolve("timeout"), SYNC_RUN_TIMEOUT_MS);
+        });
+        try {
+            const result = await Promise.race([
+                execute().then(() => "completed"),
+                timeoutPromise,
+            ]);
+            if (result === "timeout") {
+                controller.abort();
+                await this.failRun(state.runId, new Error("Magi sync run timed out after 600 seconds."));
+            }
+        }
+        catch (error) {
+            controller.abort();
+            await this.failRun(state.runId, error);
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+        return (await this.readStateByRunId(state.runId)) ?? state;
+    }
+    assertSuccessfulSyncFollowUp(state) {
+        if (state.status === "completed")
+            return;
+        throw new Error(`Synchronous follow-up ${state.command} run ${state.runId} finished with status ${state.status}.`);
+    }
     async executeReview(input) {
         const result = await runReview({
             approvalPolicy: input.repository.merge.approvalPolicy,
@@ -1347,24 +1387,30 @@ export class MagiRunManager {
             : undefined;
         const triageAutomation = input.repository.triage?.automation;
         if (followUpPr != null && triageAutomation?.merge) {
-            await this.startMerge({
+            const followUp = await this.startMerge({
                 config: input.config,
                 dryRun: input.dryRun,
                 parentSessionId: input.parentSessionId,
                 pr: followUpPr,
                 repository: input.repository,
                 signal: input.signal,
+                sync: input.sync,
             });
+            if (input.sync)
+                this.assertSuccessfulSyncFollowUp(followUp);
         }
         else if (followUpPr != null && triageAutomation?.review) {
-            await this.startReview({
+            const followUp = await this.startReview({
                 config: input.config,
                 dryRun: input.dryRun,
                 parentSessionId: input.parentSessionId,
                 pr: followUpPr,
                 repository: input.repository,
                 signal: input.signal,
+                sync: input.sync,
             });
+            if (input.sync)
+                this.assertSuccessfulSyncFollowUp(followUp);
         }
         this.active.delete(input.runId);
         this.controllers.delete(input.runId);

package/dist/prompts/contracts.js

@@ -15,26 +15,20 @@ The object must match this shape:
       "perspective": "Optional review perspective."
     }
   ],
-  "requirementFindings": [
-    {
-      "issueNumber": 47,
-      "requirement": "Required closing-issue behavior that is missing.",
-      "evidence": "Why the PR does not satisfy the requirement.",
-      "fix": "How to satisfy the requirement."
-    }
-  ],
   "reason": "Required only for CLOSE."
 }
 
 Rules:
-- MERGE requires empty findings and requirementFindings arrays.
-- CHANGES_REQUESTED requires at least one finding or requirementFinding.
-- CLOSE requires a reason and empty findings and requirementFindings arrays.
+- MERGE requires an empty findings array.
+- CHANGES_REQUESTED requires at least one finding.
+- CLOSE requires a reason and an empty findings array.
 - path must be repository-relative.
-- line is optional. Include line only when the finding targets a valid line inside the PR diff hunk.
-- startLine is allowed only when line is present and must also refer to a line inside the PR diff hunk.
-- Omit startLine for single-line findings and omit line for file-level or body-only findings.
-- Use requirementFindings only for missing closing-issue requirements; use findings for ordinary file-level issues that do not map cleanly to a diff line.
+- line is required and must target a valid right-side line inside the PR diff hunk.
+- startLine is optional and must also target a valid right-side line inside the same PR diff hunk range.
+- Omit startLine for single-line findings.
+- Do not omit line. Do not create file-level or body-only findings.
+- Missing closing-issue requirements must be normal findings anchored to the nearest responsible changed line.
+- If the problem itself does not have an exact changed line, choose the nearest changed line that represents the cause, responsibility, missing implementation, or affected behavior. This includes but is not limited to missing validation, missing wiring, missing requirements, missing tests, missing documentation, affected configuration, or relevant call sites.
 </output_contract>`.trim();
 export const rereviewOutputContract = `
 <output_contract>
@@ -46,18 +40,19 @@ The object must match this shape:
   "resolve": [{ "commentId": 123, "threadId": "..." }],
   "followUps": [{ "commentId": 123, "body": "..." }],
   "newFindings": [{ "path": "relative/path.ext", "line": 123, "startLine": 120, "body": "..." }],
-  "requirementFindings": [{ "issueNumber": 47, "requirement": "Missing requirement.", "evidence": "Why it is missing.", "fix": "How to fix it." }],
   "reason": "Required only for CLOSE."
 }
 
 Rules:
-- MERGE requires empty followUps, newFindings, and requirementFindings arrays.
-- CHANGES_REQUESTED requires at least one followUp, newFinding, or requirementFinding.
-- CLOSE requires a reason and empty followUps, newFindings, and requirementFindings arrays.
-- line is optional. Include line only when the newFinding targets a valid line inside the latest PR diff hunk.
-- startLine is allowed only when line is present and must also refer to a line inside the latest PR diff hunk.
-- Omit startLine for single-line findings and omit line for file-level or body-only findings.
-- Use requirementFindings only for missing closing-issue requirements; use newFindings for ordinary file-level issues that do not map cleanly to a diff line.
+- MERGE requires empty followUps and newFindings arrays.
+- CHANGES_REQUESTED requires at least one followUp or newFinding.
+- CLOSE requires a reason and empty followUps and newFindings arrays.
+- line is required and must target a valid right-side line inside the latest PR diff hunk.
+- startLine is optional and must also target a valid right-side line inside the same latest PR diff hunk range.
+- Omit startLine for single-line findings.
+- Do not omit line. Do not create file-level or body-only findings.
+- Missing closing-issue requirements must be normal newFindings anchored to the nearest responsible changed line.
+- If the problem itself does not have an exact changed line, choose the nearest changed line that represents the cause, responsibility, missing implementation, or affected behavior. This includes but is not limited to missing validation, missing wiring, missing requirements, missing tests, missing documentation, affected configuration, or relevant call sites.
 </output_contract>`.trim();
 export const findingValidationOutputContract = `
 <output_contract>
@@ -96,17 +91,16 @@ The object must match this shape:
       "issue": "What is wrong.",
       "fix": "How to fix it."
     }
-  ],
-  "requirementFindings": [{ "issueNumber": 47, "requirement": "Missing requirement.", "evidence": "Why it is missing.", "fix": "How to fix it." }]
+  ]
 }
 
 Rules:
-- MERGE requires empty findings and requirementFindings arrays.
-- CHANGES_REQUESTED requires at least one finding or requirementFinding.
+- MERGE requires an empty findings array.
+- CHANGES_REQUESTED requires at least one finding.
 - CLOSE is not allowed in this reconsideration step.
-- line is optional. Include line only when the finding targets a valid line inside the PR diff hunk.
-- startLine is allowed only when line is present.
-- Omit startLine for single-line findings and omit line for file-level or body-only findings.
+- line is required and must target a valid right-side line inside the PR diff hunk.
+- startLine is optional and must also target a valid right-side line inside the same PR diff hunk range.
+- Do not omit line. Do not create file-level or body-only findings.
 </output_contract>`.trim();
 export const rereviewCloseReconsiderationOutputContract = `
 <output_contract>
@@ -117,17 +111,16 @@ The object must match this shape:
   "verdict": "MERGE" | "CHANGES_REQUESTED",
   "resolve": [{ "commentId": 123, "threadId": "..." }],
   "followUps": [{ "commentId": 123, "body": "..." }],
-  "newFindings": [{ "path": "relative/path.ext", "line": 123, "startLine": 120, "body": "..." }],
-  "requirementFindings": [{ "issueNumber": 47, "requirement": "Missing requirement.", "evidence": "Why it is missing.", "fix": "How to fix it." }]
+  "newFindings": [{ "path": "relative/path.ext", "line": 123, "startLine": 120, "body": "..." }]
 }
 
 Rules:
-- MERGE requires empty followUps, newFindings, and requirementFindings arrays.
-- CHANGES_REQUESTED requires at least one followUp, newFinding, or requirementFinding.
+- MERGE requires empty followUps and newFindings arrays.
+- CHANGES_REQUESTED requires at least one followUp or newFinding.
 - CLOSE is not allowed in this reconsideration step.
-- line is optional. Include line only when the newFinding targets a valid line inside the latest PR diff hunk.
-- startLine is allowed only when line is present.
-- Omit startLine for single-line findings and omit line for file-level or body-only findings.
+- line is required and must target a valid right-side line inside the latest PR diff hunk.
+- startLine is optional and must also target a valid right-side line inside the same latest PR diff hunk range.
+- Do not omit line. Do not create file-level or body-only findings.
 </output_contract>`.trim();
 export const editOutputContract = `
 <output_contract>

package/dist/prompts/output.js

@@ -71,27 +71,16 @@ function requireNumber(value, path) {
         throw new Error(`${path} must be an integer`);
     return value;
 }
-function optionalLine(value, path) {
-    return value == null ? undefined : requireNumber(value, path);
+function requireLine(value, path) {
+    if (value == null)
+        throw new Error(`${path} is required`);
+    return requireNumber(value, path);
 }
 function optionalStartLine(input) {
     if (input.value == null)
         return undefined;
-    if (input.line == null)
-        throw new Error(`${input.path} requires line`);
     return requireNumber(input.value, input.path);
 }
-function parseRequirementFindings(value) {
-    return (value == null ? [] : requireArray(value, "requirementFindings")).map((finding, index) => {
-        const item = finding;
-        return {
-            evidence: requireString(item.evidence, `requirementFindings[${index}].evidence`),
-            fix: requireString(item.fix, `requirementFindings[${index}].fix`),
-            issueNumber: requireNumber(item.issueNumber, `requirementFindings[${index}].issueNumber`),
-            requirement: requireString(item.requirement, `requirementFindings[${index}].requirement`),
-        };
-    });
-}
 function requireOneOf(value, path, values) {
     const text = requireString(value, path);
     if (!values.includes(text)) {
@@ -179,11 +168,13 @@ export function parseReviewOutput(text) {
     const data = extractJson(text);
     if (!data || typeof data !== "object")
         throw new Error("review output must be an object");
+    if (data.requirementFindings != null)
+        throw new Error("requirementFindings is not accepted");
     if (!isVerdict(data.verdict))
         throw new Error("verdict must be MERGE, CHANGES_REQUESTED, or CLOSE");
     const findings = requireArray(data.findings, "findings").map((finding, index) => {
         const item = finding;
-        const line = optionalLine(item.line, `findings[${index}].line`);
+        const line = requireLine(item.line, `findings[${index}].line`);
         return {
             fix: requireString(item.fix, `findings[${index}].fix`),
             issue: requireString(item.issue, `findings[${index}].issue`),
@@ -199,17 +190,12 @@ export function parseReviewOutput(text) {
             }),
         };
     });
-    const requirementFindings = parseRequirementFindings(data.requirementFindings);
-    if (data.verdict === "MERGE" &&
-        (findings.length || requirementFindings.length))
-        throw new Error("MERGE requires no findings or requirementFindings");
-    if (data.verdict === "CHANGES_REQUESTED" &&
-        !findings.length &&
-        !requirementFindings.length)
-        throw new Error("CHANGES_REQUESTED requires findings or requirementFindings");
-    if (data.verdict === "CLOSE" &&
-        (findings.length || requirementFindings.length))
-        throw new Error("CLOSE requires no findings or requirementFindings");
+    if (data.verdict === "MERGE" && findings.length)
+        throw new Error("MERGE requires no findings");
+    if (data.verdict === "CHANGES_REQUESTED" && !findings.length)
+        throw new Error("CHANGES_REQUESTED requires findings");
+    if (data.verdict === "CLOSE" && findings.length)
+        throw new Error("CLOSE requires no findings");
     const reason = typeof data.reason === "string" && data.reason.trim()
         ? data.reason
         : undefined;
@@ -218,7 +204,6 @@ export function parseReviewOutput(text) {
     return {
         findings,
         reason,
-        requirementFindings,
         verdict: data.verdict,
     };
 }
@@ -226,6 +211,8 @@ export function parseRereviewOutput(text) {
     const data = extractJson(text);
     if (!isVerdict(data.verdict))
         throw new Error("rereview verdict must be MERGE, CHANGES_REQUESTED, or CLOSE");
+    if (data.requirementFindings != null)
+        throw new Error("requirementFindings is not accepted");
     const resolve = requireArray(data.resolve, "resolve").map((item, index) => {
         const value = item;
         return {
@@ -242,7 +229,7 @@ export function parseRereviewOutput(text) {
     });
     const newFindings = requireArray(data.newFindings, "newFindings").map((item, index) => {
         const value = item;
-        const line = optionalLine(value.line, `newFindings[${index}].line`);
+        const line = requireLine(value.line, `newFindings[${index}].line`);
         return {
             body: requireString(value.body, `newFindings[${index}].body`),
             line,
@@ -254,29 +241,24 @@ export function parseRereviewOutput(text) {
             }),
         };
     });
-    const requirementFindings = parseRequirementFindings(data.requirementFindings);
-    if (data.verdict === "MERGE" &&
-        (followUps.length || newFindings.length || requirementFindings.length)) {
-        throw new Error("MERGE requires no followUps, newFindings, or requirementFindings");
+    if (data.verdict === "MERGE" && (followUps.length || newFindings.length)) {
+        throw new Error("MERGE requires no followUps or newFindings");
     }
-    if (data.verdict === "CLOSE" &&
-        (followUps.length || newFindings.length || requirementFindings.length)) {
-        throw new Error("CLOSE requires no followUps, newFindings, or requirementFindings");
+    if (data.verdict === "CLOSE" && (followUps.length || newFindings.length)) {
+        throw new Error("CLOSE requires no followUps or newFindings");
     }
     if (data.verdict === "CLOSE" && !data.reason) {
         throw new Error("CLOSE requires reason");
     }
     if (data.verdict === "CHANGES_REQUESTED" &&
         !followUps.length &&
-        !newFindings.length &&
-        !requirementFindings.length) {
-        throw new Error("CHANGES_REQUESTED requires followUps, newFindings, or requirementFindings");
+        !newFindings.length) {
+        throw new Error("CHANGES_REQUESTED requires followUps or newFindings");
     }
     return {
         followUps,
         newFindings,
         reason: data.reason == null ? undefined : requireString(data.reason, "reason"),
-        requirementFindings,
         resolve,
         verdict: data.verdict,
     };

package/dist/prompts/templates/merge/edit.md

@@ -2,7 +2,7 @@ Fix pull request #{pr} for {owner}/{repo}.
 The PR worktree is {worktreePath}.
 
 Act as the PR author and address every blocking review finding listed below.
-Review findings are the complete set of requested changes. Inline findings target a PR diff line; file-level findings may not have a GitHub thread; requirement findings describe missing closing-issue requirements.
+Review findings are the complete set of requested changes. Each finding targets a PR diff line and should have a corresponding GitHub review thread unless it comes from legacy read-side state.
 {reviewFindings}
 
 Unresolved GitHub review threads are conversations that may need replies or resolution.
@@ -12,5 +12,4 @@ For each review finding and thread, decide whether you agree with the reviewer.
 If you understand and agree with the requested change, edit the code, stage changes, commit, and reply with action FIXED for each related thread.
 If a requested change in a thread is incorrect or unnecessary and you have a clear reason, do not edit for that thread; reply with action DISAGREE and explain why.
 If you cannot determine whether a threaded request is correct or what change is expected, do not blindly edit; reply with action ASK and ask a concrete question.
-File-level and requirement findings may not have a thread to reply to, but they are still blocking and must be addressed.
 Do not make changes just because a reviewer requested them. Do not push.

package/dist/prompts/templates/review/close-reconsideration.md

@@ -2,4 +2,5 @@ You requested CLOSE for pull request #{pr} in {owner}/{repo}, but the other revi
 Reconsider your decision using the existing session context and choose MERGE or CHANGES_REQUESTED instead.
 Original close reason:
 {closeReason}
+Every finding must target a valid right-side line in the PR diff. If the problem itself does not have an exact changed line, choose the nearest changed line that represents the cause, responsibility, missing implementation, or affected behavior.
 Do not edit files or perform write operations.

package/dist/prompts/templates/review/rereview.md

@@ -9,6 +9,9 @@ If there is no new commit, still reconsider the thread when a user replied after
 If you agree with the user's explanation or the code is fixed, resolve the thread.
 If you do not agree, reply in the same thread with a followUp explaining why the issue still needs changes and keep CHANGES_REQUESTED.
 Do not duplicate an existing unresolved thread as a newFinding. Use newFindings only for separate new issues.
+Every newFinding must target a valid right-side line in the PR diff.
+If the problem itself does not have an exact changed line, choose the nearest changed line that represents the cause, responsibility, missing implementation, or affected behavior. This includes but is not limited to missing validation, missing wiring, missing requirements, missing tests, missing documentation, affected configuration, or relevant call sites.
+Do not omit line. Do not create file-level or body-only newFindings.
 
 {ciFailureContextBlock}
 Do not edit files or perform write operations.

package/dist/prompts/templates/review/review.md

@@ -10,4 +10,8 @@ Request changes if a closing issue requirement is missing, only documented, only
 Do not approve solely because the PR improves the codebase if it claims to close an issue that remains incomplete.
 For referenced non-closing issues, use them as context only unless the PR body explicitly claims to complete them.
 
+Every finding must target a valid right-side line in the PR diff.
+If the problem itself does not have an exact changed line, choose the nearest changed line that represents the cause, responsibility, missing implementation, or affected behavior. This includes but is not limited to missing validation, missing wiring, missing requirements, missing tests, missing documentation, affected configuration, or relevant call sites.
+Do not omit line. Do not create file-level or body-only findings.
+
 {ciFailureContextBlock}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-magi",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Multi-agent PR review and merge orchestration plugin for OpenCode.",
   "license": "MIT",
   "author": "Hirotomo Yamada <hirotomo.yamada@avap.co.jp>",