sortie-dogs 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zufall-upon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# Sortie-dogs
+
+**Give OpenCode a task; get a bounded, validated implementation loop instead of an open-ended agent run.**
+
+![Sortie-dogs coordinating a bounded implementation workflow](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-workflow.gif)
+
+Sortie-dogs is an opt-in OpenCode orchestration plugin. It turns a task into a
+scoped plan, parallel investigation, dedicated implementation, canonical
+validation, and evidence-backed completion—while preserving standard OpenCode
+agents and settings.
+
+Requirements: Node.js 22.6 or newer, npm, and OpenCode.
+
+Guides: [日本語](docs/guide-ja.md) · [简体中文](docs/guide-zh-CN.md)
+
+## Why Sortie-dogs
+
+- **Focused when invited, invisible otherwise.** Activate it with `/sortie` or
+  select `dog-coordinator`; ordinary OpenCode sessions remain unchanged.
+- **Parallel context without uncontrolled fan-out.** Every worker handoff uses
+  exactly three bounded scouts before implementation begins.
+- **Writes stay inside the assignment.** Exact source or operation manifests
+  gate edits and handoffs.
+- **One accountable implementation path.** A dedicated Sol worker handles
+  implementation, remediation, and blocker resolution.
+- **Evidence before completion.** Canonical validation, risk-based review, and
+  terminal evidence gate coordinator-owned completion and commits.
+- **Long work can recover.** Restart recovery and bounded compaction continue
+  from retained handoff context rather than silently starting over.
+
+## The workflow
+
+1. **Brief and plan** — `dog-coordinator` turns the request into acceptance
+   criteria, a write manifest, and validation requirements.
+2. **Exactly three scouts** — bounded, read-only investigation collects
+   complementary evidence without expanding the write scope.
+3. **Dedicated worker** — the Sol worker implements only the approved manifest
+   and also owns scoped remediation or blocker resolution.
+4. **Canonical validation** — the declared test or build command must produce
+   acceptable evidence.
+5. **Risk-based review** — high-risk candidates receive independent review;
+   low-risk candidates can skip that extra pass after validation.
+6. **Coordinator completion** — only the coordinator closes the loop and owns
+   any commit after manifest, validation, review, and evidence gates pass.
+7. **Bounded continuation** — restart recovery and compaction handoffs preserve
+   progress; repeated batches remain bounded rather than becoming endless
+   delegation.
+
+## A visual walkthrough
+
+### Control complexity
+
+![Bounded roles and gates containing orchestration complexity](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-complexity.png)
+
+The coordinator keeps investigation, implementation, validation, and review in
+separate roles. Manifest gates keep their writes bounded even as the project
+gets more complex.
+
+### Finish with evidence
+
+![Validated work reaching coordinator-owned completion](https://raw.githubusercontent.com/zufall-upon/Sortie-dogs/main/docs/assets/sortie-complete.png)
+
+Validation and risk-based review happen before coordinator-owned completion, so
+the result returns with a concise record of what changed and how it was checked.
+
+## Install from npm
+
+Install the public package in the target project, then generate the
+project-local runtime files:
+
+```sh
+npm install --save-dev sortie-dogs
+npx sortie-dogs init .
+```
+
+Create `.opencode/plugins/sortie-dogs.ts` as the OpenCode plugin bridge:
+
+```ts
+export { SortieDogsPlugin } from "sortie-dogs/plugin";
+```
+
+OpenCode discovers the bridge automatically; no `plugin` entry in
+`opencode.json` is required. Restart OpenCode, then start a task:
+
+```text
+/sortie <task>
+```
+
+Selecting `dog-coordinator` directly also activates the workflow.
+
+## Scope and session guarantees
+
+The plugin is passive by default. It activates a session only when a message
+uses `/sortie` or the selected agent is `dog-coordinator`. It validates exact
+write scope through source or operation manifests and rejects invalid worker
+handoffs. Standard OpenCode agents, roles, settings, and unrelated sessions are
+preserved.
+
+On `session.idle`, the final handoff is checked and the session is released. A
+`session.deleted` event also releases it. A later request must activate the
+workflow again.
+
+## Model routing
+
+`dog-coordinator` and `dog-scout` default to `openai/gpt-5.6-luna` with the
+`xhigh` variant. This is the recommended balance: bounded prompts, concise
+scout evidence, and fewer unnecessary context or tool turns can reduce token
+use while preserving quality. Project-local routing can override either
+default.
+
+The `implementation`, `remediation`, and `blocker-resolution` roles always use
+the dedicated Sol worker; user configuration cannot replace those routes. For
+other explicitly routed roles, resolution is deterministic: Sortie-dogs tries
+the preferred target, then ordered fallbacks. Roles without either a built-in
+default or an explicit route keep OpenCode's already selected model.
+
+```json
+{
+  "modelRouting": {
+    "dog-coordinator": {
+      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "xhigh" }
+    },
+    "dog-scout": {
+      "preferred": { "model": "openai/gpt-5.6-luna", "variant": "xhigh" }
+    },
+    "dog-advisor": {
+      "preferred": { "model": "fable/opus", "variant": "thinking" },
+      "fallback": [{ "model": "provider/general" }]
+    },
+    "dog-reviewer": {
+      "preferred": { "model": "fable/opus", "variant": "thinking" },
+      "fallback": [{ "model": "provider/general" }]
+    }
+  },
+  "modelCatalog": {
+    "project": [
+      { "model": "openai/gpt-5.6-luna", "variants": ["xhigh"] },
+      { "model": "fable/opus", "variants": ["thinking"] },
+      { "model": "provider/general" }
+    ]
+  }
+}
+```
+
+Save project configuration as `.opencode/sortie-dogs.json`. `modelCatalog`
+declares provider models and named variants that are actually available;
+Sortie-dogs does not invent, probe, or translate variants. Resolution tries the
+preferred target and then its fallbacks, rejecting an explicitly routed role
+when no candidate appears in the catalog. The advisor and reviewer routes above
+are optional secondary examples; omit them when they are not needed.
+
+`dog-advisor` accepts bounded Strategy or SourceReview consultation from the
+coordinator. `dog-reviewer` independently checks high-risk candidates after
+canonical validation. Neither role implements, stages, commits, or acts as a
+user-facing worker.
+
+## Updates and migration
+
+After replacing the dependency with a newer release asset, run:
+
+```sh
+npx sortie-dogs init .
+```
+
+`init` is idempotent. It updates files owned by Sortie-dogs, migrates recognized
+older runtime files, and records the installed version in
+`.opencode/sortie-dogs.version`. Conflicting or unrecognized files remain
+untouched and initialization stops safely. User-owned configuration—including
+`.opencode/sortie-dogs.json`—and standard OpenCode files are preserved.
+
+## Safe manual removal
+
+There is no supported Sortie-dogs uninstall command. Removing the npm dependency
+is a separate package-manager operation: run `npm uninstall sortie-dogs` only in
+the directory whose `package.json` declares it. Never delete `package.json` or
+`package-lock.json` to remove the package.
+
+To remove generated runtime files manually, delete only these exact
+Sortie-dogs-owned paths:
+
+```text
+.opencode/agent/dog-coordinator.md
+.opencode/agent/dog-worker.md
+.opencode/agent/dog-scout.md
+.opencode/agent/dog-reviewer.md
+.opencode/agent/dog-advisor.md
+.opencode/command/sortie.md
+.opencode/sortie-dogs.version
+```
+
+Never delete the `.opencode`, `.opencode/agent`, or `.opencode/command`
+directories, and never use a wildcard such as `*.md`. Preserve the standard
+`plan`, `build`, and `builder` agents and every other user-owned file. Do not
+remove `.opencode/sortie-dogs.json`, the plugin bridge, other agents, or OpenCode
+settings as part of runtime-file removal.
+
+The legacy files `.opencode/agent/coordinator-mk2a2.md` and
+`.opencode/agent/sol-worker-mk2a2.md` may be removed only after an old
+Sortie-dogs marker or the content confirms Sortie-dogs ownership. If ownership
+is unclear or a filename is unexpected, stop and inspect instead of deleting.

package/dist/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function run(argv: readonly string[]): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+const core = await import(`../core/validate-schema.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`);
+const diagnostics = await import(`../core/diagnostics.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`);
+const manifestValidator = await import(`../core/validate-manifest.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`);
+const pathUtils = await import(`../core/path.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`);
+const initializer = await import(`../core/initialize.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`);
+const LIMITS = {
+    handoffBytes: 2 * 1024 * 1024,
+    manifestBytes: 512 * 1024,
+    changedPathsBytes: 1024 * 1024,
+    changedPaths: 10_000,
+    arrayItems: 10_000,
+    pathCharacters: 512,
+    jsonDepth: 32,
+};
+const USAGE = `Usage: sortie-dogs lint <handoff.json> [<handoff.json> ...]
+  [--manifest <operation-manifest.json>]
+  [--changed-paths-from <file|->]
+  [--changed-path <path> ...]
+  [--format text|json] [--quiet] [--strict]`;
+const INIT_USAGE = "Usage: sortie-dogs init [project-root]";
+class InputFailure extends Error {
+    safeMessage;
+    constructor(safeMessage) {
+        super(safeMessage);
+        this.name = "InputFailure";
+        this.safeMessage = safeMessage;
+    }
+}
+function parseArguments(argv) {
+    if (argv[0] === "--help") {
+        return argv.length === 1 ? { kind: "help" } : { kind: "usage" };
+    }
+    if (argv[0] !== "lint")
+        return { kind: "usage" };
+    const parsed = {
+        handoffs: [],
+        changedPaths: [],
+        changedPathsProvided: false,
+        format: "text",
+        quiet: false,
+        strict: false,
+    };
+    for (let index = 1; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--help")
+            return { kind: "help" };
+        if (argument === "--quiet" || argument === "--strict") {
+            parsed[argument === "--quiet" ? "quiet" : "strict"] = true;
+            continue;
+        }
+        if (argument === "--manifest" || argument === "--changed-paths-from" ||
+            argument === "--changed-path" || argument === "--format") {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("--"))
+                return { kind: "usage" };
+            index += 1;
+            if (argument === "--manifest") {
+                if (parsed.manifest !== undefined)
+                    return { kind: "usage" };
+                parsed.manifest = value;
+            }
+            else if (argument === "--changed-paths-from") {
+                if (parsed.changedPathsFrom !== undefined)
+                    return { kind: "usage" };
+                parsed.changedPathsFrom = value;
+                parsed.changedPathsProvided = true;
+            }
+            else if (argument === "--changed-path") {
+                parsed.changedPaths.push(value);
+                parsed.changedPathsProvided = true;
+            }
+            else {
+                if (value !== "text" && value !== "json")
+                    return { kind: "usage" };
+                parsed.format = value;
+            }
+            continue;
+        }
+        if (argument.startsWith("-"))
+            return { kind: "usage" };
+        parsed.handoffs.push(argument);
+    }
+    return parsed.handoffs.length === 0 ? { kind: "usage" } : { kind: "run", value: parsed };
+}
+async function readBoundedFile(file, limit, label) {
+    let handle;
+    try {
+        handle = await open(file, "r");
+        const buffer = Buffer.allocUnsafe(limit + 1);
+        let length = 0;
+        while (length <= limit) {
+            const result = await handle.read(buffer, length, buffer.length - length, null);
+            if (result.bytesRead === 0)
+                return buffer.subarray(0, length);
+            length += result.bytesRead;
+        }
+        throw new InputFailure(`${label} exceeds the size limit.`);
+    }
+    catch (error) {
+        if (error instanceof InputFailure)
+            throw error;
+        throw new InputFailure(`${label} could not be read.`);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function readBoundedStdin(limit) {
+    const chunks = [];
+    let length = 0;
+    try {
+        for await (const chunk of process.stdin) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            length += buffer.length;
+            if (length > limit)
+                throw new InputFailure("Changed paths input exceeds the size limit.");
+            chunks.push(buffer);
+        }
+    }
+    catch (error) {
+        if (error instanceof InputFailure)
+            throw error;
+        throw new InputFailure("Changed paths input could not be read.");
+    }
+    return Buffer.concat(chunks, length);
+}
+function checkJsonResources(value) {
+    const pending = [{ value, depth: 1 }];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const isContainer = Array.isArray(current.value) ||
+            (current.value !== null && typeof current.value === "object");
+        if (isContainer && current.depth > LIMITS.jsonDepth) {
+            throw new InputFailure("JSON input exceeds the nesting depth limit.");
+        }
+        if (Array.isArray(current.value)) {
+            if (current.value.length > LIMITS.arrayItems) {
+                throw new InputFailure("JSON input exceeds the array item limit.");
+            }
+            for (const item of current.value)
+                pending.push({ value: item, depth: current.depth + 1 });
+        }
+        else if (current.value !== null && typeof current.value === "object") {
+            for (const item of Object.values(current.value)) {
+                pending.push({ value: item, depth: current.depth + 1 });
+            }
+        }
+    }
+}
+function parseJson(buffer, label) {
+    let value;
+    try {
+        value = JSON.parse(buffer.toString("utf8"));
+    }
+    catch {
+        throw new InputFailure(`${label} is not valid JSON.`);
+    }
+    checkJsonResources(value);
+    return value;
+}
+function normalizeChangedPaths(paths) {
+    const normalized = new Set();
+    for (const path of paths) {
+        if (path.length > LIMITS.pathCharacters) {
+            throw new InputFailure("Changed paths input is invalid.");
+        }
+        try {
+            normalized.add(pathUtils.normalizeRelativePath(path));
+        }
+        catch (error) {
+            if (!(error instanceof pathUtils.RelativePathError))
+                throw error;
+            throw new InputFailure("Changed paths input is invalid.");
+        }
+        if (normalized.size > LIMITS.changedPaths) {
+            throw new InputFailure("Changed paths input exceeds the count limit.");
+        }
+    }
+    return [...normalized];
+}
+function changedPathLines(buffer) {
+    return buffer.toString("utf8").split(/\r?\n/u).filter((line) => line.length > 0);
+}
+function safeSchemaPointer(diagnostic) {
+    if (diagnostic.code !== "schema_additionalProperties")
+        return diagnostic.pointer;
+    const slash = diagnostic.pointer.lastIndexOf("/");
+    return `${diagnostic.pointer.slice(0, Math.max(0, slash))}/@unknown`;
+}
+function associate(file, input) {
+    return input.map((diagnostic) => ({
+        file,
+        code: diagnostic.code,
+        severity: diagnostic.severity,
+        pointer: diagnostic.code.startsWith("schema_")
+            ? safeSchemaPointer(diagnostic)
+            : diagnostic.pointer,
+        message: diagnostic.message,
+    }));
+}
+function neutralizeTextControlCharacters(value) {
+    return [...value].map((character) => {
+        const codePoint = character.codePointAt(0);
+        if (codePoint === 0x0a)
+            return "\\n";
+        if (codePoint === 0x0d)
+            return "\\r";
+        if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
+            return `\\u${codePoint.toString(16).padStart(4, "0")}`;
+        }
+        return character;
+    }).join("");
+}
+function render(output, format) {
+    if (format === "json")
+        return `${JSON.stringify(output)}\n`;
+    return output.map(({ file, pointer, code, severity, message }) => `${file} ${neutralizeTextControlCharacters(pointer || "/")} ${code} ${severity} ${neutralizeTextControlCharacters(message)}\n`).join("");
+}
+export async function run(argv) {
+    if (argv[0] === "init") {
+        if (argv[1] === "--help" && argv.length === 2) {
+            process.stdout.write(`${INIT_USAGE}\n`);
+            return 0;
+        }
+        if (argv.length > 2 || argv[1]?.startsWith("-") === true) {
+            process.stderr.write(`${INIT_USAGE}\n`);
+            return 2;
+        }
+        try {
+            const initialized = await initializer.initializeProject(argv[1]);
+            process.stdout.write(initialized.status === "installed"
+                ? `Initialized Sortie-dogs ${initialized.version}.\n`
+                : `Sortie-dogs ${initialized.version} is already initialized.\n`);
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(error instanceof initializer.ProjectInitializationError
+                ? `${error.message}\n`
+                : "Initialization failed.\n");
+            return 2;
+        }
+    }
+    const result = parseArguments(argv);
+    if (result.kind === "help") {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    if (result.kind === "usage") {
+        process.stderr.write(`${USAGE}\n`);
+        return 2;
+    }
+    const options = result.value;
+    const output = [];
+    const failures = [];
+    let manifest;
+    let changedPaths;
+    let changedPathsResolved = true;
+    if (options.manifest !== undefined) {
+        try {
+            const value = parseJson(await readBoundedFile(options.manifest, LIMITS.manifestBytes, "Manifest input"), "Manifest input");
+            const validation = core.validateOperationManifestSchema(value);
+            if (validation.ok)
+                manifest = validation.value;
+            else
+                output.push(...associate("manifest", validation.diagnostics));
+        }
+        catch (error) {
+            failures.push(error instanceof InputFailure ? error.safeMessage : "Manifest input could not be processed.");
+        }
+    }
+    try {
+        const fromFile = options.changedPathsFrom === undefined
+            ? []
+            : changedPathLines(options.changedPathsFrom === "-"
+                ? await readBoundedStdin(LIMITS.changedPathsBytes)
+                : await readBoundedFile(options.changedPathsFrom, LIMITS.changedPathsBytes, "Changed paths input"));
+        changedPaths = normalizeChangedPaths([...fromFile, ...options.changedPaths]);
+    }
+    catch (error) {
+        changedPathsResolved = false;
+        failures.push(error instanceof InputFailure ? error.safeMessage : "Changed paths input could not be processed.");
+    }
+    for (let index = 0; index < options.handoffs.length; index += 1) {
+        const file = `handoff[${index}]`;
+        try {
+            const value = parseJson(await readBoundedFile(options.handoffs[index], LIMITS.handoffBytes, "Handoff input"), "Handoff input");
+            const validation = core.validateHandoffSchema(value);
+            if (!validation.ok) {
+                output.push(...associate(file, validation.diagnostics));
+                continue;
+            }
+            output.push(...associate(file, diagnostics.lint(validation.value).diagnostics));
+            if (manifest !== undefined && changedPathsResolved) {
+                output.push(...associate(file, manifestValidator.validateManifest(validation.value, manifest, changedPaths, options.changedPathsProvided)));
+            }
+        }
+        catch (error) {
+            failures.push(error instanceof InputFailure ? error.safeMessage : "Handoff input could not be processed.");
+        }
+    }
+    if (!options.quiet)
+        process.stdout.write(render(output, options.format));
+    for (const failure of failures)
+        process.stderr.write(`${failure}\n`);
+    if (failures.length > 0)
+        return 2;
+    const hasFailure = output.some(({ severity }) => severity === "error" ||
+        (options.strict && severity === "warning"));
+    return hasFailure ? 1 : 0;
+}
+if (process.argv[1] !== undefined && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+    process.exitCode = await run(process.argv.slice(2));
+}

package/dist/core/diagnostics.d.ts

@@ -0,0 +1,2 @@
+import type { Handoff, LintOptions, LintResult } from "./types.js";
+export declare function lint(handoff: Handoff, options?: LintOptions): LintResult;

package/dist/core/diagnostics.js

@@ -0,0 +1,65 @@
+const validateSemantics = await import(`./validate-semantics.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`);
+const DEFAULT_SEVERITIES = {
+    H001: "error",
+    H002: "error",
+    H003: "error",
+    H004: "error",
+    H005: "error",
+    H006: "error",
+    H007: "error",
+    H008: "error",
+    H009: "warning",
+    H010: "error",
+};
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function comparePointer(left, right) {
+    const leftSegments = left.split("/");
+    const rightSegments = right.split("/");
+    const length = Math.min(leftSegments.length, rightSegments.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftSegment = leftSegments[index];
+        const rightSegment = rightSegments[index];
+        if (leftSegment === rightSegment)
+            continue;
+        if (/^\d+$/.test(leftSegment) && /^\d+$/.test(rightSegment)) {
+            const numericOrder = BigInt(leftSegment) < BigInt(rightSegment) ? -1 : BigInt(leftSegment) > BigInt(rightSegment) ? 1 : 0;
+            if (numericOrder !== 0)
+                return numericOrder;
+        }
+        return compareText(leftSegment, rightSegment);
+    }
+    return leftSegments.length - rightSegments.length;
+}
+function compareDiagnostics(left, right) {
+    return (comparePointer(left.pointer, right.pointer) ||
+        compareText(left.code, right.code));
+}
+function createLintResult(issues, profile, options = {}) {
+    const enabledCodes = options.codes === undefined ? undefined : new Set(options.codes);
+    const severityOverrides = options.severity;
+    const diagnostics = issues
+        .filter((issue) => enabledCodes === undefined || enabledCodes.has(issue.code))
+        .map((issue) => ({
+        code: issue.code,
+        severity: severityOverrides?.[issue.code] ??
+            (issue.code === "H006" && profile === "minimal"
+                ? "warning"
+                : DEFAULT_SEVERITIES[issue.code]),
+        pointer: issue.path,
+        message: issue.message,
+    }))
+        .sort(compareDiagnostics);
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const diagnostic of diagnostics)
+        counts[diagnostic.severity] += 1;
+    return {
+        diagnostics,
+        counts,
+        ok: counts.error === 0,
+    };
+}
+export function lint(handoff, options) {
+    return createLintResult(validateSemantics.lintHandoff(handoff), handoff.profile, options);
+}

package/dist/core/initialize.d.ts

@@ -0,0 +1,14 @@
+export type InitializationStatus = "installed" | "unchanged";
+export interface InitializeProjectResult {
+    readonly status: InitializationStatus;
+    readonly version: string;
+    readonly installedPaths: readonly string[];
+    readonly preservedLegacyPaths: readonly string[];
+}
+export type ProjectInitializationErrorCode = "conflict" | "incompatible-version" | "invalid-project" | "unsafe-path" | "write-failed";
+export declare class ProjectInitializationError extends Error {
+    readonly code: ProjectInitializationErrorCode;
+    constructor(code: ProjectInitializationErrorCode, message: string, options?: ErrorOptions);
+}
+/** Installs the packaged runtime into one existing project without changing user settings. */
+export declare function initializeProject(projectRoot?: string): Promise<InitializeProjectResult>;