@kontourai/flow-agents 3.7.0 → 3.9.0

package/src/cli/workflow-sidecar.ts

@@ -915,7 +915,9 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     if (!check.id) continue;
     const subjectId = `${slug}/${check.id}`;
     const fieldOrBehavior = String(check.summary ?? check.id);
-    const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+    const gateClaimIdentityVersion = check._gate_claim_identity_version === 2 ? 2 : 1;
+    const gateClaimRecordedAt = gateClaimIdentityVersion === 2 && typeof check._gate_claim_recorded_at === "string" ? check._gate_claim_recorded_at : null;
+    const claimId = generateClaimId(subjectId, "flow-agents.workflow", gateClaimRecordedAt ? `${fieldOrBehavior}::gate-visit::${gateClaimRecordedAt}` : fieldOrBehavior);
     const evId = `ev:${claimId}`;
     const legacyClaimType = `workflow.check.${check.kind ?? "external"}`;
 
@@ -1071,7 +1073,7 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
       // restored stamp) takes the currently-active step's id.
       const declaredStepId = gateClaimDeclaredStepId ?? (activeStep ? activeStep.stepId : null);
       const declaredMetadata: AnyObj = gateClaimExpectationId
-        ? { ...claimMetadata, gate_claim: { expectation_id: gateClaimExpectationId, claim_type: declared.claimType, subject_type: declared.subjectType, step_id: declaredStepId, ...(gateClaimRouteReason ? { route_reason: gateClaimRouteReason } : {}) } }
+        ? { ...claimMetadata, gate_claim: { expectation_id: gateClaimExpectationId, claim_type: declared.claimType, subject_type: declared.subjectType, step_id: declaredStepId, ...(gateClaimIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(gateClaimRecordedAt ? { recorded_at: gateClaimRecordedAt } : {}), ...(gateClaimRouteReason ? { route_reason: gateClaimRouteReason } : {}) } }
         : claimMetadata;
       const declaredClaimObj: AnyObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, ...(declaredMetadata ? { metadata: declaredMetadata } : {}) };
       const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj as Record<string, unknown>, evidence: [evItem] as Record<string, unknown>[], events: claimEvents as Record<string, unknown>[], policies: [declaredPolicy] as Record<string, unknown>[] });
@@ -1089,7 +1091,9 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     if (!criterion.id) continue;
     const subjectId = `${slug}/${criterion.id}`;
     const fieldOrBehavior = String(criterion.description ?? criterion.id);
-    const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+    const criterionIdentityVersion = criterion.identity_version === 2 ? 2 : 1;
+    const criterionVerifiedAt = criterionIdentityVersion === 2 && typeof criterion.verified_at === "string" ? criterion.verified_at : null;
+    const claimId = generateClaimId(subjectId, "flow-agents.workflow", criterionVerifiedAt ? `${fieldOrBehavior}::verified::${criterionVerifiedAt}` : fieldOrBehavior);
     const legacyClaimType = "workflow.acceptance.criterion";
     const policy = ensurePolicy(legacyClaimType, "high", []);
     const evStatus = criterionStatusToEventStatus(String(criterion.status ?? ""));
@@ -1105,7 +1109,7 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     if (declared) {
       // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
       const declaredPolicy = ensurePolicy(declared.claimType, "high", []);
-      const declaredClaimObj: AnyObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [] }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
+      const declaredClaimObj: AnyObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [], ...(criterionIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(criterionVerifiedAt ? { verified_at: criterionVerifiedAt } : {}) }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
       const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj as Record<string, unknown>, evidence: [], events: claimEvents as Record<string, unknown>[], policies: [declaredPolicy] as Record<string, unknown>[] });
       claims.push({ ...declaredClaimObj, status: declaredStatus });
     } else {
@@ -1128,10 +1132,12 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     const supersededBy = typeof c.superseded_by === "string" && c.superseded_by.length > 0 ? c.superseded_by : null;
     const critiqueReviewer = String(c.reviewer ?? "tool-code-reviewer");
     const critiqueReviewedAt = String(c.reviewed_at ?? ts);
+    const critiqueIdentityVersion = c.identity_version === 2 ? 2 : 1;
     const critMeta: AnyObj = {
       origin: "critique",
       reviewer: critiqueReviewer,
       reviewed_at: critiqueReviewedAt,
+      ...(critiqueIdentityVersion === 2 ? { identity_version: 2 } : {}),
       findings: Array.isArray(c.findings) ? c.findings : [],
       lanes: Array.isArray(c.lanes) ? c.lanes : [],
       review_target: c.review_target && typeof c.review_target === "object" ? c.review_target : { artifacts: [] },
@@ -1143,7 +1149,9 @@ export async function buildTrustBundle(slug: string, timestamp: string, checks:
     // A superseded historical write gets a distinct, stable claimId so it co-exists with the live
     // claim of the same critique id (never overwrites or duplicates it). The salt is reproducible
     // across rebuilds because superseded_by + reviewed_at are preserved in metadata.
-    const claimIdSalt = supersededBy ? `${fieldOrBehavior}::superseded::${supersededBy}::${critiqueReviewedAt}` : fieldOrBehavior;
+    const claimIdSalt = critiqueIdentityVersion === 2
+      ? `${fieldOrBehavior}::reviewed::${critiqueReviewedAt}${supersededBy ? `::superseded::${supersededBy}` : ""}`
+      : (supersededBy ? `${fieldOrBehavior}::superseded::${supersededBy}::${critiqueReviewedAt}` : fieldOrBehavior);
     const claimId = generateClaimId(subjectId, "flow-agents.workflow", claimIdSalt);
     const legacyClaimType = "workflow.critique.review";
     const policy = ensurePolicy(legacyClaimType, "medium", []);
@@ -2727,7 +2735,7 @@ function requireObservedCommandRefs(refs: AnyObj[], observedCommands: ReadonlySe
   }
 }
 
-function completePassingCriteria(existing: AnyObj[], raw: string[], observedCommands: ReadonlySet<string>): AnyObj[] {
+function completePassingCriteria(existing: AnyObj[], raw: string[], observedCommands: ReadonlySet<string>, verifiedAt: string): AnyObj[] {
   if (raw.length === 0) die("record-gate-claim requires --criterion-json for a passing tests-evidence claim");
   const incoming = raw.map((value) => parseJson(value, "--criterion-json"));
   const expectedById = new Map<string, AnyObj>();
@@ -2746,7 +2754,7 @@ function completePassingCriteria(existing: AnyObj[], raw: string[], observedComm
     const refs = normalizeEvidenceRefs(criterion.evidence_refs, `criterion ${ids[index]} evidence_refs`);
     if (refs.length === 0) die(`criterion ${ids[index]} requires reviewable evidence_refs`);
     requireObservedCommandRefs(refs, observedCommands, `criterion ${ids[index]}`);
-    return { ...expectedById.get(ids[index])!, status: "pass", evidence_refs: refs };
+    return { ...expectedById.get(ids[index])!, status: "pass", evidence_refs: refs, identity_version: 2, verified_at: verifiedAt };
   });
 }
 
@@ -3133,6 +3141,8 @@ function checksFromBundle(dir: string): AnyObj[] {
     if (typeof gc.claim_type === "string") check._gate_claim_declared_type = gc.claim_type;
     if (typeof gc.subject_type === "string") check._gate_claim_declared_subject = gc.subject_type;
     if (typeof gc.step_id === "string") check._gate_claim_declared_step_id = gc.step_id;
+    if (typeof gc.recorded_at === "string") check._gate_claim_recorded_at = gc.recorded_at;
+    if (gc.identity_version === 2) check._gate_claim_identity_version = 2;
     if (typeof gc.route_reason === "string") check._gate_claim_route_reason = gc.route_reason;
   };
   // #270 CRITICAL/HIGH fix: a claim that is gate-claim-SHAPED but carries NO metadata.gate_claim
@@ -3294,6 +3304,7 @@ function critiquesFromBundle(dir: string): AnyObj[] {
       review_target: md.review_target && typeof md.review_target === "object" && !Array.isArray(md.review_target) ? md.review_target : { artifacts: [] },
       reviewer: typeof md.reviewer === "string" ? md.reviewer : "tool-code-reviewer",
       reviewed_at: typeof md.reviewed_at === "string" ? md.reviewed_at : (c.updatedAt || c.createdAt || now()),
+      ...(md.identity_version === 2 ? { identity_version: 2 } : {}),
       artifact_refs: Array.isArray(md.artifact_refs) ? md.artifact_refs : [],
       ...(typeof md.superseded_by === "string" && md.superseded_by.length > 0 ? { superseded_by: md.superseded_by } : {}),
     };
@@ -3314,6 +3325,8 @@ function criteriaFromBundle(dir: string): AnyObj[] {
         description: typeof saved.description === "string" ? saved.description : (claim.fieldOrBehavior || ""),
         status: typeof saved.status === "string" ? saved.status : (claim.value ?? "not_verified"),
         evidence_refs: Array.isArray(saved.evidence_refs) ? saved.evidence_refs : [],
+        ...(typeof saved.verified_at === "string" ? { verified_at: saved.verified_at } : {}),
+        ...(saved.identity_version === 2 ? { identity_version: 2 } : {}),
       };
     })
     .filter((criterion: AnyObj) => typeof criterion.id === "string" && criterion.id.length > 0);
@@ -3369,7 +3382,7 @@ async function recordEvidence(p: ReturnType<typeof parseArgs>): Promise<number>
   if (!checks.length && opts(p, "surface-trust-json").length === 0) die("record-evidence requires at least one --check-json or --surface-trust-json");
   validateAcceptanceEvidenceRefs(dir, p);
   // Phase 4c: bundle is the sole verification artifact — stop writing evidence.json and acceptance.json update.
-  const ts = opt(p, "timestamp", now());
+  const ts = opt(p, "timestamp", new Date().toISOString());
   // #298: readBundleState + merge-by-id instead of unconditionally replacing every prior check —
   // record-evidence previously never called checksFromBundle(dir), so it dropped every check
   // recorded by an earlier record-evidence/record-check/record-gate-claim call. A later check
@@ -3576,7 +3589,7 @@ function diagnostic(dir: string, code: string, summary: string): never {
 async function recordGateClaim(p: ReturnType<typeof parseArgs>): Promise<number> {
   const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
   const slug = taskSlugFor(dir, opt(p, "task-slug"));
-  const ts = opt(p, "timestamp", now());
+  const ts = opt(p, "timestamp", new Date().toISOString());
   const statusVal = opt(p, "status");
   if (!["pass", "fail", "not_verified"].includes(statusVal)) die("--status must be one of: pass, fail, not_verified");
   const summary = opt(p, "summary") || die("--summary is required");
@@ -3652,6 +3665,8 @@ async function recordGateClaim(p: ReturnType<typeof parseArgs>): Promise<number>
     status: statusVal,
     summary,
     _gate_claim_expectation_id: targetExpectation.id,
+    _gate_claim_identity_version: 2,
+    _gate_claim_recorded_at: ts,
     ...(routeReason ? { _gate_claim_route_reason: routeReason } : {}),
   };
 
@@ -3690,7 +3705,7 @@ async function recordGateClaim(p: ReturnType<typeof parseArgs>): Promise<number>
   // SAME expectation id supersedes the earlier check for that expectation (mergeChecksById); a
   // gate claim against a different expectation is additive.
   const _existingState = readBundleState(dir);
-  const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommandNames) : _existingState.criteria;
+  const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommandNames, ts) : _existingState.criteria;
   if (mustRunTests) {
     const liveCritiques = _existingState.critiques.filter((critique) => !critique.superseded_by);
     if (liveCritiques.length === 0 || liveCritiques.some((critique) => !critiqueIsCleanAndCurrent(dir, critique))) {
@@ -3907,7 +3922,8 @@ async function recordCritique(p: ReturnType<typeof parseArgs>): Promise<number>
   const critique = {
     id: critiqueId,
     reviewer: opt(p, "reviewer", "tool-code-reviewer"),
-    reviewed_at: opt(p, "timestamp", now()),
+    reviewed_at: opt(p, "timestamp", new Date().toISOString()),
+    identity_version: 2,
     verdict,
     summary,
     lanes,

package/src/cli/workflow.ts

@@ -6,6 +6,7 @@ import { isDeepStrictEqual } from "node:util";
 import { fileURLToPath } from "node:url";
 import { validateDefinition } from "@kontourai/flow";
 import { loadBuilderFlowRun } from "../builder-flow-run-adapter.js";
+import { driveBuilderFlowSession, withContinuationDriverLock } from "../continuation-driver.js";
 import { inspectBuilderFlowSession, recoverBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
 import { flowAgentsPackageRoot, flowAgentsPackageVersion } from "../lib/package-version.js";
 import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
@@ -14,6 +15,7 @@ import { flagBool, flagList, flagString, parseArgs } from "../lib/args.js";
 import { main as builderRun } from "./builder-run.js";
 import { currentWorkflowSessionDir, isMeaningfulTestCommand, mainFromPublicWorkflow, WORKFLOW_WRITER_CONTRACT_VERSION } from "./workflow-sidecar.js";
 import { resolveCurrentAssignmentActor, withSubjectLock } from "./assignment-provider.js";
+import { executeLoadedContinuationAdapter, loadContinuationAdapterCommand, waitForContinuationBarrier } from "./continuation-adapter.js";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -22,7 +24,7 @@ const PACKAGE_ROOT = flowAgentsPackageRoot();
 const REQUIRE = createRequire(import.meta.url);
 const PACKAGE_METADATA = readJsonFile(path.join(PACKAGE_ROOT, "package.json"), "Flow Agents package metadata");
 const CLI_VERSION = flowAgentsPackageVersion();
-const PUBLIC_VERBS = ["start", "status", "evidence", "critique", "pause", "resume", "release", "cancel", "archive", "doctor"] as const;
+const PUBLIC_VERBS = ["start", "status", "evidence", "critique", "drive", "pause", "resume", "release", "cancel", "archive", "doctor"] as const;
 
 function usage(): void {
   console.log(`Usage: flow-agents workflow <verb> [options]
@@ -32,6 +34,7 @@ Public workflow verbs:
   status              Show the current canonical run and projected next action.
   evidence            Record evidence for the current Flow gate and synchronize it.
   critique            Record review critique directly into the current trust bundle.
+  drive               Continue the canonical run through an explicit runtime adapter.
   pause               Pause the current run as its assignment actor.
   resume              Resume the current paused run as its assignment actor.
   release             Release the current assignment without canceling the run.
@@ -61,12 +64,41 @@ export async function main(argv: string[]): Promise<number> {
   if (verb === "status") return status(sessionDir, flagBool(parsed.flags, "json"));
   if (verb === "evidence") return evidence(sessionDir, argv.slice(1), flagBool(parsed.flags, "json"));
   if (verb === "critique") return critique(sessionDir, argv.slice(1), flagBool(parsed.flags, "json"));
+  if (verb === "drive") return drive(sessionDir, argv.slice(1), flagBool(parsed.flags, "json"));
 
   const forwarded = stripPublicFlags(argv.slice(1), new Set(["artifact-root", "session-dir", "json"]));
   if (verb === "release" && !flagString(parsed.flags, "reason")) throw new Error("workflow release requires --reason <text>");
   return builderRun([verb === "release" ? "release-assignment" : verb, "--session-dir", sessionDir, ...forwarded]);
 }
 
+async function drive(sessionDir: string, argv: string[], json: boolean): Promise<number> {
+  const parsed = parseArgs(argv);
+  assertOnlyFlags(parsed.flags, new Set(["artifact-root", "session-dir", "json", "adapter-command-file", "max-turns", "turn-timeout-ms", "barrier-wait-ms", "barrier-poll-ms"]), "workflow drive");
+  const adapterCommandFile = flagString(parsed.flags, "adapter-command-file");
+  if (!adapterCommandFile) throw new Error("workflow drive requires --adapter-command-file <path>");
+  const maxTurns = integerFlag(parsed.flags, "max-turns", 4, 1, 100);
+  const turnTimeoutMs = integerFlag(parsed.flags, "turn-timeout-ms", 900_000, 1, 86_400_000);
+  const barrierWaitMs = integerFlag(parsed.flags, "barrier-wait-ms", 300_000, 0, 86_400_000);
+  const barrierPollMs = integerFlag(parsed.flags, "barrier-poll-ms", 1_000, 1, 60_000);
+  const { slug, projectRoot } = readBoundSession(sessionDir);
+  assertMatchingAssignmentActor(sessionDir, slug);
+  const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
+  const result = await withContinuationDriverLock(sessionDir, async () => {
+    assertMatchingAssignmentActor(sessionDir, slug);
+    return driveBuilderFlowSession({
+      sessionDir,
+      maxTurns,
+      adapterCommandIdentity: adapterCommand.identity,
+      authorizeTurn: async () => { assertMatchingAssignmentActor(sessionDir, slug); },
+      execute: async (request) => executeLoadedContinuationAdapter(adapterCommand, request, { cwd: projectRoot, timeoutMs: turnTimeoutMs }),
+      waitForBarrier: async (barrier) => waitForContinuationBarrier(barrier, { maxWaitMs: barrierWaitMs, pollMs: barrierPollMs }),
+    });
+  });
+  if (json) console.log(JSON.stringify(result));
+  else console.log(`Continuation driver ${result.outcome} after ${result.turns_started} turn(s); canonical Flow is ${result.snapshot.status} at ${result.snapshot.current_step}.`);
+  return 0;
+}
+
 async function start(argv: string[]): Promise<number> {
   const parsed = parseArgs(argv);
   assertOnlyFlags(parsed.flags, new Set(["flow", "work-item", "task-slug", "artifact-root", "source-request", "summary", "title", "criterion", "assignment-provider", "effective-state-json"]), "workflow start");
@@ -193,7 +225,7 @@ async function evidence(sessionDir: string, argv: string[], json: boolean): Prom
     // session state cannot change mid-invocation.
     const caller = assertMatchingAssignmentActor(sessionDir, slug);
     const repaired = await recoverBuilderFlowSession({ sessionDir });
-    const beforeEvidence = manifestEvidenceDigests(repaired.run.manifest);
+    const beforeEvidence = manifestEvidenceIdentity(repaired.run.manifest);
     await mainFromPublicWorkflow([
       "record-gate-claim",
       sessionDir,
@@ -202,26 +234,33 @@ async function evidence(sessionDir: string, argv: string[], json: boolean): Prom
       caller.actorKey,
     ]);
 
-    await syncBuilderFlowSession({ sessionDir });
+    const synchronized = await syncBuilderFlowSession({ sessionDir });
 
     const digest = fileSha256(path.join(sessionDir, "trust.bundle"));
     const run = await loadBuilderFlowRun({ cwd: repaired.projectRoot, runId: slug });
-    const afterEvidence = manifestEvidenceDigests(run.manifest);
-    const newEvidence = afterEvidence.filter((value) => !beforeEvidence.includes(value));
-    if (newEvidence.length !== 1 || newEvidence[0] !== digest) {
+    const afterEvidence = manifestEvidenceIdentity(run.manifest);
+    const beforeIds = new Set(beforeEvidence.map((entry) => entry.id));
+    const newEvidence = afterEvidence.filter((entry) => !beforeIds.has(entry.id));
+    if (synchronized.attached && (newEvidence.length !== 1 || newEvidence[0]?.sha256 !== digest)) {
       throw new Error("workflow evidence did not attach exactly this invocation's resulting trust.bundle digest");
     }
+    if (!synchronized.attached && newEvidence.length !== 0) {
+      throw new Error("workflow evidence changed the canonical manifest while synchronization reported no attachment");
+    }
     const updatedSidecar = readBoundSession(sessionDir).sidecar;
     return immutableReport({
       run_id: run.runId,
       status: run.state.status,
       current_step: run.state.current_step,
-      attached: true,
+      attached: synchronized.attached,
+      awaiting_evidence: !synchronized.attached,
       next_action: updatedSidecar.next_action ?? null,
     });
   });
   if (json) console.log(JSON.stringify(report));
-  else console.log(`Recorded evidence; canonical run is ${report.status} at ${report.current_step}.`);
+  else console.log(report.attached
+    ? `Recorded evidence; canonical run is ${report.status} at ${report.current_step}.`
+    : `Recorded evidence; canonical run is awaiting the remaining gate expectations at ${report.current_step}.`);
   return 0;
 }
 
@@ -511,11 +550,14 @@ function immutableReport<T>(value: T): T {
   return Object.freeze(value);
 }
 
-function manifestEvidenceDigests(manifest: JsonRecord): string[] {
+function manifestEvidenceIdentity(manifest: JsonRecord): Array<{ id: string; sha256: string }> {
   const evidence = Array.isArray(manifest.evidence) ? manifest.evidence : [];
   return evidence
-    .map((entry) => entry && typeof entry === "object" ? (entry as JsonRecord).sha256 : null)
-    .filter((digest): digest is string => typeof digest === "string");
+    .flatMap((entry) => entry && typeof entry === "object"
+      && typeof (entry as JsonRecord).id === "string"
+      && typeof (entry as JsonRecord).sha256 === "string"
+      ? [{ id: String((entry as JsonRecord).id), sha256: String((entry as JsonRecord).sha256) }]
+      : []);
 }
 
 function optionalFileDigest(file: string): string | null {
@@ -560,6 +602,21 @@ function assertOnlyFlags(flags: ReturnType<typeof parseArgs>["flags"], allowed:
   if (unsupported) throw new Error(`${command} does not support --${unsupported}`);
 }
 
+function integerFlag(
+  flags: ReturnType<typeof parseArgs>["flags"],
+  name: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const raw = flagString(flags, name);
+  if (raw === undefined) return fallback;
+  if (!/^(0|[1-9][0-9]*)$/.test(raw)) throw new Error(`workflow drive --${name} must be an integer from ${min} through ${max}`);
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`workflow drive --${name} must be an integer from ${min} through ${max}`);
+  return value;
+}
+
 function isWithin(candidate: string, root: string): boolean {
   const relative = path.relative(root, candidate);
   return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));