@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/lib/internal/task-review.ts

@@ -2,6 +2,7 @@ import { finalizeReviewSummary } from '../task/review-finalization.ts';
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
@@ -16,7 +17,8 @@ function failUsage(message: string): void {
   process.exitCode = 2;
 }
 
-function taskReview(args: string[] = []): void {
+async function taskReview(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-review', args)) return;
   if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
     return;
@@ -25,7 +27,7 @@ function taskReview(args: string[] = []): void {
     failUsage('task ref and intent are required');
     return;
   }
-  if (args[1] !== 'finalize-summary') {
+  if (!internalHandlerRoute('task-review', 'finalize-summary', args[1] ?? '')) {
     failUsage(`unknown intent '${args[1]}'`);
     return;
   }
@@ -78,11 +80,11 @@ function taskReview(args: string[] = []): void {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => {
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', async () => {
       let current = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true });
       if (current.status !== 'failed' || !overrideTicket) return current;
       if (!overrideTarget || !overrideScope) { failUsage('override ticket requires target and scope'); return current; }
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef: args[0]!, ticketId: overrideTicket,
         failureId: failureId('review-finalization', current.error?.code ?? 'TASK_STATE_MISMATCH'),
         target: overrideTarget, scope: overrideScope

package/lib/internal/task-short-id.ts

@@ -2,6 +2,7 @@ import path from 'node:path';
 
 import { detectRepoRoot } from '../task/resolve-ref.ts';
 import { configuredShortIdLength, executeShortIdCommand } from '../task/short-id.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-short-id <alloc|release|resolve|list> [argument] [--active-dir <path>] [--short-id-length <N>] [--verify]\n`;
 
@@ -12,9 +13,17 @@ function failure(message: string): void {
 }
 
 function taskShortId(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('task-short-id', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['alloc', 'release', 'resolve', 'list'].includes(operation)) { failure('a valid short-id operation is required'); return; }
+  const route = operation === 'list' && args.includes('--verify') ? 'list-verify' : operation ?? '';
+  if (!operation || ![
+    internalHandlerRoute('task-short-id', 'alloc', route),
+    internalHandlerRoute('task-short-id', 'release', route),
+    internalHandlerRoute('task-short-id', 'resolve', route),
+    internalHandlerRoute('task-short-id', 'list', route),
+    internalHandlerRoute('task-short-id', 'list-verify', route)
+  ].some(Boolean)) { failure('a valid short-id operation is required'); return; }
   const positional: string[] = [];
   let activeDir: string | null = null;
   let shortIdLength: number | null = null;

package/lib/internal/task-snapshot.ts

@@ -1,4 +1,5 @@
 import { collectTaskSnapshot } from '../task/snapshot.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-snapshot <N | TASK-id> [--format json|text]\n';
 
@@ -9,8 +10,9 @@ function fail(message: string): void {
 }
 
 function taskSnapshot(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('task-snapshot', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (!args[0] || args[0].startsWith('--')) { fail('task ref is required'); return; }
+  if (!args[0] || args[0].startsWith('--') || !internalHandlerRoute('task-snapshot', 'snapshot', 'snapshot')) { fail('task ref is required'); return; }
   let format: 'json' | 'text' = 'json';
   let seenFormat = false;
   for (let index = 1; index < args.length; index += 1) {

package/lib/internal/task-validate.ts

@@ -24,6 +24,7 @@ import {
 } from '../sandbox/control/protocol.ts';
 import { getProcessStartTime } from '../server/process-state.ts';
 import { assertGitWorktreeBinding } from '../git/worktree-identity.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-validate <branch | TASK-id | N> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] -- <command> [args...]`;
 const MAX_TIMEOUT_MS = 60 * 60 * 1000;
@@ -271,6 +272,7 @@ function sniffFormat(args: string[]): 'text' | 'json' {
 }
 
 function taskValidate(args: string[]): void {
+  if (!ensureInternalHandlerRoute('task-validate', args)) return;
   let options: ValidateOptions;
   try {
     options = parseValidateArgs(args);
@@ -287,9 +289,11 @@ function taskValidate(args: string[]): void {
     const target = resolveSandboxTarget(options.target, config.repoRoot);
     const commit = git(config.repoRoot, ['rev-parse', target.branch]);
     const startedAt = new Date().toISOString();
-    const result = options.scope === 'snapshot'
+    const result = internalHandlerRoute('task-validate', 'snapshot', options.scope)
       ? snapshotValidation(config.repoRoot, commit, options)
-      : inplaceValidation(config, target, options);
+      : internalHandlerRoute('task-validate', 'inplace', options.scope)
+        ? inplaceValidation(config, target, options)
+        : (() => { throw new Error('TASK_VALIDATE_SCOPE_UNREGISTERED'); })();
     const evidence = {
       version: 1,
       taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,

package/lib/internal/task-verify.ts

@@ -2,6 +2,7 @@ import { renderTaskVerification, verifyTaskEvent } from '../task/verification.ts
 import { consumeHumanOverride, failureId } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
@@ -11,9 +12,11 @@ function fail(message: string): void {
   process.exitCode = 1;
 }
 
-function taskVerify(args: string[] = []): void {
+async function taskVerify(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-verify', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')) { fail('task ref and verification event are required'); return; }
+  if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')
+    || !internalHandlerRoute('task-verify', 'event', args[1] ? 'event' : '')) { fail('task ref and verification event are required'); return; }
   const taskRef = args[0];
   const event = args[1];
   let artifact: string | undefined;
@@ -41,8 +44,8 @@ function taskVerify(args: string[] = []): void {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-verify.${event}`, () => {
-      let current = verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) });
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-verify.${event}`, async () => {
+      let current = await verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) });
       if (current.status === 'pass' || !overrideTicket) return current;
       if (!overrideTarget || !overrideScope) { fail('override ticket requires target and scope'); return current; }
       const failureProducer = current.status === 'blocked' || current.status === 'fail'
@@ -53,13 +56,13 @@ function taskVerify(args: string[] = []): void {
         : current.status === 'fail'
           ? 'CHECK_FAILED'
           : current.error?.code ?? 'VERIFY_TASK_STATE_MISMATCH';
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef, ticketId: overrideTicket,
         failureId: failureId(failureProducer, failureCode),
         target: overrideTarget, scope: overrideScope
       }, {
-        effectExecutor: (capability) => {
-          const retried = verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) }, { manualOverride: capability });
+        effectExecutor: async (capability) => {
+          const retried = await verifyTaskEvent({ taskRef, event, ...(artifact ? { artifact } : {}) }, { manualOverride: capability });
           current = retried;
           return retried.status !== 'pass'
             ? { code: 'OVERRIDE_EFFECT_FAILED', message: `${retried.error?.code ?? 'VERIFY_FAILED'}: ${retried.error?.message ?? 'manual verification effect failed'}` }

package/lib/internal/task-warning.ts

@@ -3,6 +3,7 @@ import type { WorkflowWarningIntent } from '../task/workflow-warning-intents.ts'
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-warning <task-ref> <add|set-status|list> [intent flags] [--dry-run]\n`;
 const FLAGS: Record<string, string> = {
@@ -17,10 +18,15 @@ function usageFailure(message: string): void {
   process.exitCode = 1;
 }
 
-function taskWarning(args: string[] = []): void {
+async function taskWarning(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-warning', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const [taskRef, kind] = args;
-  if (!taskRef || !kind || !['add', 'set-status', 'list'].includes(kind)) { usageFailure('task ref and a valid intent are required'); return; }
+  if (!taskRef || !kind || ![
+    internalHandlerRoute('task-warning', 'add', kind ?? ''),
+    internalHandlerRoute('task-warning', 'set-status', kind ?? ''),
+    internalHandlerRoute('task-warning', 'list', kind ?? '')
+  ].some(Boolean)) { usageFailure('task ref and a valid intent are required'); return; }
   const values: Record<string, unknown> = { kind, taskRef };
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
@@ -54,11 +60,11 @@ function taskWarning(args: string[] = []): void {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-warning.${kind}`, () => {
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-warning.${kind}`, async () => {
       let current = applyWorkflowWarningIntent(values as WorkflowWarningIntent);
       if (current.status !== 'failed' || !values.overrideTicket) return current;
       if (!values.overrideTarget || !values.overrideScope) { usageFailure('override ticket requires target and scope'); return current; }
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef, ticketId: String(values.overrideTicket),
         failureId: failureId('workflow-warning', current.error?.code ?? 'TASK_STATE_MISMATCH'),
         target: String(values.overrideTarget), scope: String(values.overrideScope)

package/lib/platform/adapters.ts

@@ -1,4 +1,5 @@
 import type { PlatformError, PlatformResult } from './types.ts';
+import type { ResourceIdentity } from './resource-identity.ts';
 
 type PlatformAdapterContext = {
   cwd: string;
@@ -28,6 +29,7 @@ type PlatformChangeRequestSnapshot = {
   assignees: string[];
   milestone: string | null;
   mergeability?: PlatformMergeability;
+  identity?: ResourceIdentity;
 };
 
 type PlatformCheckSnapshot = {
@@ -105,8 +107,7 @@ function registerPlatformCapabilities(
     'inspectChangeRequest' | 'inspectIssueClosingChangeRequests' | 'inspectRequiredChecks' | 'resolveChangeRequestGitEvidence'
   >
 ): void {
-  const adapter = adapters.get(type);
-  if (!adapter) throw new Error(`Platform adapter '${type}' must be registered before its capabilities`);
+  const adapter = adapters.get(type) ?? { type } as PlatformAdapter;
   adapters.set(type, { ...adapter, ...capabilities });
 }
 

package/lib/platform/change-request-git-evidence.ts

@@ -3,7 +3,13 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
 
-import { resolvePlatformChangeRequestGitEvidence } from "./adapters.ts";
+import { resolvePlatformProviderContext } from './context.ts';
+import {
+  providerError,
+  providerOperationContext,
+  unsupportedProviderOperation
+} from './provider-bridge.ts';
+import { isResourceIdentity } from './resource-identity.ts';
 import { resolveReviewedHeadRelation } from "./merged-pr-equivalence.ts";
 import type { ReviewedHeadRelation } from "./merged-pr-equivalence.ts";
 import type { PullRequestSnapshot } from "./pull-requests.ts";
@@ -53,25 +59,46 @@ function validMergeIdentity(lastReviewedCommit: string, pullRequest: PullRequest
   return null;
 }
 
-function resolveMaterializedReviewedHeadRelation(input: {
+async function resolveMaterializedReviewedHeadRelation(input: {
   cwd: string;
   platformType: string | null;
   lastReviewedCommit: string;
   pullRequest: PullRequestSnapshot;
-}): ReviewedHeadRelation {
+}): Promise<ReviewedHeadRelation> {
   const identityFailure = validMergeIdentity(input.lastReviewedCommit, input.pullRequest);
   if (identityFailure) return identityFailure;
 
-  const source = resolvePlatformChangeRequestGitEvidence(input.platformType, {
+  const loaded = await resolvePlatformProviderContext({
     cwd: input.cwd,
-    repository: input.pullRequest.repository,
-    number: input.pullRequest.number,
-    pullRequest: input.pullRequest
+    platformType: input.platformType || undefined
   });
+  if (!loaded.ok) {
+    return blocked(
+      loaded.context.error?.code || 'PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE',
+      loaded.context.error?.message || 'Unable to resolve the configured platform provider'
+    );
+  }
+  const target = isResourceIdentity(input.pullRequest.identity)
+    ? input.pullRequest.identity
+    : { kind: 'number' as const, value: input.pullRequest.number };
+  const operation = loaded.value.provider.changeRequests?.resolveGitEvidence
+    ? await loaded.value.provider.changeRequests.resolveGitEvidence({
+      context: providerOperationContext(loaded.value),
+      target,
+      expected: {
+        baseSha: input.pullRequest.base.sha,
+        headSha: input.pullRequest.head.sha,
+        targetBranch: input.pullRequest.base.ref
+      }
+    })
+    : unsupportedProviderOperation(loaded.value.provider, 'changeRequests.resolveGitEvidence');
+  const source = operation.ok
+    ? operation
+    : { ok: false as const, error: providerError(operation.error, 'PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE') };
   if (!source.ok || !source.value) {
     return blocked(
-      source.error?.code || "PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE",
-      source.error?.message || "Unable to resolve authoritative PR Git evidence"
+      ('error' in source && source.error?.code) || "PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE",
+      ('error' in source && source.error?.message) || "Unable to resolve authoritative PR Git evidence"
     );
   }
   if (

package/lib/platform/comment-safety.ts

@@ -0,0 +1,250 @@
+type SanitizationError = { code: 'COMMENT_DOCUMENT_INVALID'; message: string; offset: number };
+type SanitizationResult<T> = { ok: true; value: T } | { ok: false; error: SanitizationError };
+type SanitizationOptions = { reservedMarkers?: readonly RegExp[] };
+type PlaceholderSplit = { prefix: string; suffix: string };
+type FenceRange = {
+  start: number;
+  end: number;
+  openingEnd: number;
+  closingStart: number;
+  character: '`' | '~';
+  opening: string;
+  closing: string;
+};
+type Line = { start: number; end: number; text: string };
+
+const CONTROL_MARKER_PATTERN = /<!--\s*(?:sync-issue|sync-pr|last-commit)\b[\s\S]*?-->|<!--\s*canonical-pr-change-report\s*-->/gi;
+
+function ok<T>(value: T): SanitizationResult<T> {
+  return { ok: true, value };
+}
+
+function invalid(message: string, offset: number): SanitizationResult<never> {
+  return { ok: false, error: { code: 'COMMENT_DOCUMENT_INVALID', message, offset } };
+}
+
+function normalized(value: string): string {
+  return value.replace(/\r\n?/g, '\n');
+}
+
+function linesOf(value: string): Line[] {
+  const lines: Line[] = [];
+  let start = 0;
+  while (start < value.length) {
+    const newline = value.indexOf('\n', start);
+    const end = newline === -1 ? value.length : newline;
+    lines.push({ start, end: newline === -1 ? end : newline + 1, text: value.slice(start, end) });
+    start = newline === -1 ? value.length : newline + 1;
+  }
+  if (value.length === 0) lines.push({ start: 0, end: 0, text: '' });
+  return lines;
+}
+
+function openingFence(line: string): { character: '`' | '~'; length: number } | null | 'invalid' {
+  const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+  if (!match) return null;
+  const character = match[1]![0] as '`' | '~';
+  const info = match[2]!;
+  if (character === '`' && info.includes('`')) return 'invalid';
+  return { character, length: match[1]!.length };
+}
+
+function closesFence(line: string, fence: { character: '`' | '~'; length: number }): boolean {
+  const escaped = fence.character === '`' ? '`' : '~';
+  return new RegExp(`^ {0,3}${escaped}{${fence.length},}[ \\t]*$`).test(line);
+}
+
+function fenceRanges(value: string): SanitizationResult<FenceRange[]> {
+  const ranges: FenceRange[] = [];
+  let fence: { character: '`' | '~'; length: number; start: number; openingEnd: number } | null = null;
+  for (const line of linesOf(value)) {
+    if (!fence) {
+      const opening = openingFence(line.text);
+      if (opening === 'invalid') return invalid('fenced code info string is invalid', line.start);
+      if (opening) fence = { ...opening, start: line.start, openingEnd: line.end };
+      continue;
+    }
+    if (closesFence(line.text, fence)) {
+      ranges.push({
+        start: fence.start,
+        end: line.end,
+        openingEnd: fence.openingEnd,
+        closingStart: line.start,
+        character: fence.character,
+        opening: value.slice(fence.start, fence.openingEnd),
+        closing: value.slice(line.start, line.end)
+      });
+      fence = null;
+    }
+  }
+  if (fence) return invalid('fenced code block is not closed', fence.start);
+  return ok(ranges);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function escapeHtmlText(value: string): string {
+  return escapeHtml(value);
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return escapeHtml(value);
+}
+
+function escapeMarkdownLiteral(value: string): string {
+  return value.replace(/[\\`*_{}\[\]()#+.!|<>-]/g, '\\$&');
+}
+
+function markerSafe(value: string, markers: readonly RegExp[]): string {
+  let result = value;
+  for (const marker of markers) {
+    const flags = marker.flags.includes('g') ? marker.flags : `${marker.flags}g`;
+    const pattern = new RegExp(marker.source, flags);
+    result = result.replace(pattern, (match) => escapeHtmlText(match));
+  }
+  return result;
+}
+
+function tagEnd(value: string, start: number): number {
+  let quote: '"' | "'" | null = null;
+  for (let index = start + 1; index < value.length; index += 1) {
+    const character = value[index]!;
+    if (quote) {
+      if (character === quote) quote = null;
+    } else if (character === '"' || character === "'") {
+      quote = character;
+    } else if (character === '>') {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function isMarkdownAutolink(value: string, start: number): boolean {
+  const end = value.indexOf('>', start + 1);
+  if (end === -1) return false;
+  const target = value.slice(start + 1, end);
+  return /^(?:https?:\/\/|mailto:)[^<>\s]+$/i.test(target)
+    || /^[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+$/.test(target);
+}
+
+function sanitizeOutside(value: string, baseOffset: number): SanitizationResult<string> {
+  let result = '';
+  let index = 0;
+  while (index < value.length) {
+    if (value.startsWith('<!--', index)) {
+      const end = value.indexOf('-->', index + 4);
+      if (end === -1) return invalid('HTML comment is not closed', baseOffset + index);
+      const token = value.slice(index, end + 3);
+      result += escapeHtmlText(token);
+      index = end + 3;
+      continue;
+    }
+    if (value[index] === '<' && isMarkdownAutolink(value, index)) {
+      const end = value.indexOf('>', index + 1);
+      result += value.slice(index, end + 1);
+      index = end + 1;
+      continue;
+    }
+    if (value[index] === '<' && /[\\/!?A-Za-z]/.test(value[index + 1] || '')) {
+      const end = tagEnd(value, index);
+      if (end === -1) return invalid('HTML-like tag is not closed', baseOffset + index);
+      result += escapeHtmlText(value.slice(index, end + 1));
+      index = end + 1;
+      continue;
+    }
+    result += value[index]!;
+    index += 1;
+  }
+  return ok(result);
+}
+
+function sanitizeMarkdownDocument(value: string, options: SanitizationOptions = {}): SanitizationResult<string> {
+  const source = normalized(value);
+  const ranges = fenceRanges(source);
+  if (!ranges.ok) return ranges;
+  const markers = options.reservedMarkers || [];
+  let result = '';
+  let cursor = 0;
+  for (const range of ranges.value) {
+    const outside = sanitizeOutside(source.slice(cursor, range.start), cursor);
+    if (!outside.ok) return outside;
+    result += outside.value;
+    result += markerSafe(source.slice(range.start, range.end), markers);
+    cursor = range.end;
+  }
+  const tail = sanitizeOutside(source.slice(cursor), cursor);
+  if (!tail.ok) return tail;
+  return ok(result + tail.value);
+}
+
+function renderSafeCodeFence(value: string, language = '', reservedMarkers: readonly RegExp[] = [CONTROL_MARKER_PATTERN]): string {
+  const content = markerSafe(normalized(value), reservedMarkers);
+  const longestRun = Math.max(0, ...(content.match(/`+/g) || []).map((run) => run.length));
+  const delimiter = '`'.repeat(Math.max(3, longestRun + 1));
+  const suffix = content.endsWith('\n') ? '' : '\n';
+  return `${delimiter}${language}\n${content}${suffix}${delimiter}`;
+}
+
+function commentRangesOutsideFences(source: string, ranges: readonly FenceRange[]): SanitizationResult<Array<{ start: number; end: number }>> {
+  const comments: Array<{ start: number; end: number }> = [];
+  let cursor = 0;
+  for (const fence of [...ranges, { start: source.length, end: source.length }]) {
+    const segment = source.slice(cursor, fence.start);
+    let index = 0;
+    while (index < segment.length) {
+      const opening = segment.indexOf('<!--', index);
+      if (opening === -1) break;
+      const absoluteStart = cursor + opening;
+      const closing = segment.indexOf('-->', opening + 4);
+      if (closing === -1) return invalid('HTML comment is not closed', absoluteStart);
+      comments.push({ start: absoluteStart, end: cursor + closing + 3 });
+      index = closing + 3;
+    }
+    cursor = fence.end;
+  }
+  return ok(comments);
+}
+
+function splitDocumentPlaceholder(value: string, placeholder: string): SanitizationResult<PlaceholderSplit> {
+  const source = normalized(value);
+  const ranges = fenceRanges(source);
+  if (!ranges.ok) return ranges;
+  const positions: number[] = [];
+  let cursor = source.indexOf(placeholder);
+  while (cursor !== -1) {
+    positions.push(cursor);
+    cursor = source.indexOf(placeholder, cursor + placeholder.length);
+  }
+  if (positions.length !== 1) return invalid('document must contain exactly one placeholder', positions[1] ?? positions[0] ?? source.length);
+  const position = positions[0]!;
+  if (ranges.value.some((range) => position >= range.start && position < range.end)) {
+    return invalid('placeholder must be outside fenced code', position);
+  }
+  const comments = commentRangesOutsideFences(source, ranges.value);
+  if (!comments.ok) return comments;
+  const containing = comments.value.find((comment) => position >= comment.start && position < comment.end);
+  if (containing && (containing.start !== position || containing.end !== position + placeholder.length)) {
+    return invalid('placeholder must not be nested in another HTML comment', position);
+  }
+  return ok({ prefix: source.slice(0, position), suffix: source.slice(position + placeholder.length) });
+}
+
+export {
+  CONTROL_MARKER_PATTERN,
+  escapeHtmlAttribute,
+  escapeHtmlText,
+  escapeMarkdownLiteral,
+  fenceRanges,
+  renderSafeCodeFence,
+  sanitizeMarkdownDocument,
+  splitDocumentPlaceholder
+};
+export type { FenceRange, SanitizationError, SanitizationOptions, SanitizationResult };

package/lib/platform/completion-backfill.ts

@@ -9,11 +9,12 @@ import { getOpenWorkflowWarnings } from '../task/workflow-warnings.ts';
 import { applyWorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
 import { captureTaskWriteMetadata } from '../task/write.ts';
 import { syncPlatformComment } from './issue-comments.ts';
-import type { GitHubClient } from './github-client.ts';
+import type { PlatformClient } from './context.ts';
 import { platformResult } from './types.ts';
 import type { PlatformOperation, PlatformResult } from './types.ts';
+import { taskIssueIdentity } from './task-identities.ts';
 
-type CompletionBackfillOptions = { agent: string; cwd?: string; client?: GitHubClient };
+type CompletionBackfillOptions = { agent: string; cwd?: string; client?: PlatformClient };
 type CompletionBackfillResult = PlatformResult & {
   artifacts: Array<{ artifact: string; status: PlatformResult['status'] }>;
   warnings: Array<{ id: string; status: string }>;
@@ -42,10 +43,10 @@ function excludedPrReview(taskDir: string, message: string): string | null {
   }
 }
 
-function backfillCompletionComments(
+async function backfillCompletionComments(
   taskRef: string,
   options: CompletionBackfillOptions
-): CompletionBackfillResult {
+): Promise<CompletionBackfillResult> {
   const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
   if (!resolved.ok) return result(platformResult('failed', {
     error: { code: resolved.code, message: resolved.message, retryable: false }
@@ -59,16 +60,16 @@ function backfillCompletionComments(
     }
   }), [], []);
   const initialContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
-  const issueNumber = Number(parseTaskFrontmatter(initialContent).issue_number);
-  if (!Number.isInteger(issueNumber) || issueNumber <= 0) return result(platformResult('no-op', {
-    error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no valid issue_number', retryable: false }
+  const issueIdentity = taskIssueIdentity(parseTaskFrontmatter(initialContent));
+  if (!issueIdentity) return result(platformResult('no-op', {
+    error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no valid platform issue identity', retryable: false }
   }), [], []);
 
   const artifacts: CompletionBackfillResult['artifacts'] = [];
   const operations: PlatformOperation[] = [];
   let latest = platformResult('no-op', { error: null });
   for (const artifact of inventory.artifacts) {
-    latest = syncPlatformComment(resolved.taskId, {
+    latest = await syncPlatformComment(resolved.taskId, {
       kind: 'artifact',
       artifact: artifact.name,
       agent: options.agent,