agentic-orchestrator 0.1.25 → 0.1.26

package/dist/apps/control-plane/application/services/qa-index-service.js

@@ -2,11 +2,58 @@ import { atomicWriteJson, readJson, stableHash } from '../../core/fs.js';
 import { applyQaUpdates, summarizeQaIndex } from '../../core/qa-index.js';
 import { ERROR_CODES } from '../../core/error-codes.js';
 import { fail } from '../../core/response.js';
+/**
+ * Manages QA test obligation tracking.
+ *
+ * ## Responsibilities
+ * - Create qa_test_index.json from diff hunks
+ * - Track test status per hunk (pending/covered/skipped)
+ * - Link evidence to test obligations
+ * - Validate all obligations are resolved
+ *
+ * ## Dependencies
+ * Depends on {@link QaIndexServicePort} for:
+ * - QA index file path resolution
+ * - Schema validation
+ *
+ * ## Key Methods
+ * - `qaTestIndexGet()` - retrieve test index
+ * - `qaTestIndexUpdate()` - update hunk statuses with evidence
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - index file does not exist
+ * - VERSION_CONFLICT - concurrent index update
+ * - SCHEMA_VALIDATION_FAILED - invalid index structure
+ *
+ * @example
+ * ```typescript
+ * const qaService = new QaIndexService(port);
+ * const index = await qaService.qaTestIndexGet('my_feature');
+ * await qaService.qaTestIndexUpdate('my_feature', updates, 1);
+ * ```
+ *
+ * ## Index Format
+ * Each hunk has: path, line range, required tests, status, evidence refs
+ */
 export class QaIndexService {
     port;
     constructor(port) {
         this.port = port;
     }
+    /**
+     * Retrieves QA test index for a feature.
+     *
+     * @param featureId - feature identifier
+     * @returns Test index with hunk obligations and pending summary
+     * @throws FILE_NOT_FOUND - index does not exist
+     *
+     * @example
+     * ```typescript
+     * const index = await qaService.qaTestIndexGet('my_feature');
+     * console.log(index.data.items);
+     * console.log(index.data.pending_obligations);
+     * ```
+     */
     async qaTestIndexGet(featureId) {
         const index = await readJson(this.port.qaIndexPath(featureId), {
             feature_id: featureId,
@@ -33,6 +80,23 @@ export class QaIndexService {
             },
         };
     }
+    /**
+     * Updates hunk statuses with evidence references and version guard.
+     *
+     * @param featureId - feature identifier
+     * @param updates - hunk status updates with evidence refs
+     * @param expectedVersion - expected index version
+     * @returns Updated index
+     * @throws VERSION_CONFLICT - version mismatch
+     * @throws SCHEMA_VALIDATION_FAILED - invalid updates
+     *
+     * @example
+     * ```typescript
+     * await qaService.qaTestIndexUpdate('my_feature', {
+     *   items: [{ path: 'file.ts', status: 'covered', evidence_refs: ['gate_123'] }]
+     * }, 1);
+     * ```
+     */
     async qaTestIndexUpdate(featureId, expectedVersion, updates, evidenceRefs) {
         const current = await readJson(this.port.qaIndexPath(featureId), null);
         if (!current) {

package/dist/apps/control-plane/application/services/qa-index-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"qa-index-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/qa-index-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAU9C,MAAM,OAAO,cAAc;IACR,IAAI,CAAqB;IAE1C,YAAY,IAAwB;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,SAAiB;QAOpC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE;YAC7D,UAAU,EAAE,SAAS;YACrB,OAAO,EAAE,CAAC;YACV,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC;YACpC,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QAEH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;QACtF,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM;gBACJ,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,+BAA+B,EAAE;oBACpF,MAAM,EAAE,UAAU,CAAC,MAAM;oBACzB,SAAS,EAAE,KAAK;oBAChB,cAAc,EAAE,IAAI;iBACrB,CAAC;aACH,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACxC,OAAO;YACL,IAAI,EAAE;gBACJ,KAAK;gBACL,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,sBAAsB,EAAE,OAAO,CAAC,eAAe;aAChD;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,iBAAiB,CACrB,SAAiB,EACjB,eAA8B,EAC9B,OAAgB,EAChB,YAAuB;QAEvB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;QACvE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM;gBACJ,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,8BAA8B,EAAE;oBACnF,SAAS,EAAE,KAAK;oBAChB,cAAc,EAAE,IAAI;iBACrB,CAAC;aACH,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,cAAc,CACzB,OAAO,EACP,eAAe,EACf,OAA+C,EAC/C,YAAoD,CACrD,CAAC;QACF,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,2BAA2B,EAAE,IAAI,CAAC,CAAC;QACrF,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM;gBACJ,kBAAkB,EAAE,IAAI,CACtB,WAAW,CAAC,cAAc,EAC1B,wCAAwC,EACxC;oBACE,MAAM,EAAE,UAAU,CAAC,MAAM;oBACzB,SAAS,EAAE,KAAK;oBAChB,cAAc,EAAE,IAAI;iBACrB,CACF;aACF,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;QAE9D,OAAO;YACL,IAAI,EAAE;gBACJ,UAAU,EAAE,SAAS;gBACrB,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"qa-index-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/qa-index-service.ts"],"names":[],"mappings":"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"}

package/dist/apps/control-plane/application/services/reactions-service.d.ts

@@ -1,5 +1,8 @@
 import type { ToolCaller as SupervisorToolCaller } from '../../core/tool-caller.js';
 import type { NotifierService } from './notifier-service.js';
+/**
+ * @fileoverview Event-driven reactions and retry policy service.
+ */
 export interface GateFailedReaction {
     enabled: boolean;
     max_retries: number;
@@ -51,6 +54,47 @@ export interface ReactionsServiceDependencies {
     notifier?: NotifierService;
     policy?: ReactionsPolicy;
 }
+/**
+ * Manages event-driven reactions and retry policies.
+ *
+ * ## Responsibilities
+ * - Execute reactions for events (gate_failed, agent_stuck, collision_detected, etc.)
+ * - Enforce retry limits and backoff
+ * - Trigger escalation when limits exceeded
+ * - Record reaction outcomes
+ *
+ * ## Dependencies
+ * Depends on:
+ * - {@link SupervisorToolCaller} - for tool invocation
+ * - {@link NotifierService} - for escalation notifications
+ * - Policy reactions configuration
+ *
+ * ## Key Methods
+ * - `shouldRetry()` - determine if retry is allowed
+ * - `waitBeforeRetry()` - apply retry delay
+ * - `recordRetry()` - log retry attempt
+ * - `notifyEscalation()` - escalate to human
+ *
+ * ## Error Conditions
+ * - RETRY_LIMIT_EXCEEDED - max retries reached
+ * - REACTION_NOT_CONFIGURED - no reaction defined for event
+ *
+ * @example
+ * ```typescript
+ * const reactionsService = new ReactionsService({ toolCaller, notifier, policy });
+ * if (reactionsService.shouldRetry('my_feature', 1)) {
+ *   await reactionsService.waitBeforeRetry();
+ *   await reactionsService.recordRetry('my_feature', 2);
+ * }
+ * ```
+ *
+ * ## Supported Events
+ * - gate_failed: retry with feedback
+ * - agent_stuck: restart or escalate
+ * - collision_detected: re-drive queue
+ * - ready_to_merge: notify reviewers
+ * - changes_requested: restart QA phase
+ */
 export declare class ReactionsService {
     private readonly toolCaller;
     private readonly notifier;
@@ -59,9 +103,41 @@ export declare class ReactionsService {
     shouldRetry(_featureId: string, retryCount: number): boolean;
     retryDelayMs(): number;
     maxRetries(): number;
+    /**
+     * Waits for retry delay before next attempt.
+     *
+     * @returns Promise that resolves after delay
+     *
+     * @example
+     * ```typescript
+     * await reactionsService.waitBeforeRetry();
+     * ```
+     */
     waitBeforeRetry(): Promise<void>;
     buildRepairPrompt(ctx: GateRepairContext): string;
+    /**
+     * Records retry attempt in feature state.
+     *
+     * @param featureId - feature identifier
+     * @param retryCount - current retry count
+     *
+     * @example
+     * ```typescript
+     * await reactionsService.recordRetry('my_feature', 2);
+     * ```
+     */
     recordRetry(featureId: string, retryCount: number): Promise<void>;
     shouldEscalate(retryCount: number): boolean;
+    /**
+     * Notifies escalation when retry limit exceeded.
+     *
+     * @param featureId - feature identifier
+     * @param ctx - gate repair context with failure details
+     *
+     * @example
+     * ```typescript
+     * await reactionsService.notifyEscalation('my_feature', context);
+     * ```
+     */
     notifyEscalation(featureId: string, ctx: GateRepairContext): Promise<void>;
 }

package/dist/apps/control-plane/application/services/reactions-service.js

@@ -6,6 +6,47 @@ const DEFAULT_GATE_FAILED_REACTION = {
     escalate_after: 2,
     retry_delay_ms: 30000,
 };
+/**
+ * Manages event-driven reactions and retry policies.
+ *
+ * ## Responsibilities
+ * - Execute reactions for events (gate_failed, agent_stuck, collision_detected, etc.)
+ * - Enforce retry limits and backoff
+ * - Trigger escalation when limits exceeded
+ * - Record reaction outcomes
+ *
+ * ## Dependencies
+ * Depends on:
+ * - {@link SupervisorToolCaller} - for tool invocation
+ * - {@link NotifierService} - for escalation notifications
+ * - Policy reactions configuration
+ *
+ * ## Key Methods
+ * - `shouldRetry()` - determine if retry is allowed
+ * - `waitBeforeRetry()` - apply retry delay
+ * - `recordRetry()` - log retry attempt
+ * - `notifyEscalation()` - escalate to human
+ *
+ * ## Error Conditions
+ * - RETRY_LIMIT_EXCEEDED - max retries reached
+ * - REACTION_NOT_CONFIGURED - no reaction defined for event
+ *
+ * @example
+ * ```typescript
+ * const reactionsService = new ReactionsService({ toolCaller, notifier, policy });
+ * if (reactionsService.shouldRetry('my_feature', 1)) {
+ *   await reactionsService.waitBeforeRetry();
+ *   await reactionsService.recordRetry('my_feature', 2);
+ * }
+ * ```
+ *
+ * ## Supported Events
+ * - gate_failed: retry with feedback
+ * - agent_stuck: restart or escalate
+ * - collision_detected: re-drive queue
+ * - ready_to_merge: notify reviewers
+ * - changes_requested: restart QA phase
+ */
 export class ReactionsService {
     toolCaller;
     notifier;
@@ -43,6 +84,16 @@ export class ReactionsService {
         }
         return DEFAULT_GATE_FAILED_REACTION.max_retries;
     }
+    /**
+     * Waits for retry delay before next attempt.
+     *
+     * @returns Promise that resolves after delay
+     *
+     * @example
+     * ```typescript
+     * await reactionsService.waitBeforeRetry();
+     * ```
+     */
     async waitBeforeRetry() {
         const delayMs = this.retryDelayMs();
         if (delayMs <= 0) {
@@ -78,6 +129,17 @@ export class ReactionsService {
             failureSummary,
         ].join('\n');
     }
+    /**
+     * Records retry attempt in feature state.
+     *
+     * @param featureId - feature identifier
+     * @param retryCount - current retry count
+     *
+     * @example
+     * ```typescript
+     * await reactionsService.recordRetry('my_feature', 2);
+     * ```
+     */
     async recordRetry(featureId, retryCount) {
         const current = await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_GET, { feature_id: featureId });
         await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
@@ -95,6 +157,17 @@ export class ReactionsService {
         const reaction = this.policy.gate_failed ?? DEFAULT_GATE_FAILED_REACTION;
         return retryCount >= reaction.escalate_after;
     }
+    /**
+     * Notifies escalation when retry limit exceeded.
+     *
+     * @param featureId - feature identifier
+     * @param ctx - gate repair context with failure details
+     *
+     * @example
+     * ```typescript
+     * await reactionsService.notifyEscalation('my_feature', context);
+     * ```
+     */
     async notifyEscalation(featureId, ctx) {
         if (!this.notifier) {
             return;

package/dist/apps/control-plane/application/services/reactions-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactions-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/reactions-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reactions-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/reactions-service.ts"],"names":[],"mappings":"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"}

package/dist/apps/control-plane/application/services/reporting-service.d.ts

@@ -1,4 +1,7 @@
 type AnyRecord = Record<string, any>;
+/**
+ * @fileoverview Dashboard and feature summary reporting service.
+ */
 export interface ReportingServicePort {
     collectAcceptedPlans(excludeFeatureId?: string | null): Promise<AnyRecord[]>;
     getPolicySnapshot(): AnyRecord;
@@ -20,20 +23,95 @@ export interface ReportingServicePort {
         data: AnyRecord;
     }>;
 }
+/**
+ * Manages dashboard and feature summary generation.
+ *
+ * ## Responsibilities
+ * - Generate report.dashboard with global index snapshot
+ * - Generate report.feature_summary with per-feature details
+ * - Aggregate cost and PR metadata
+ * - Provide gate profile summaries
+ *
+ * ## Dependencies
+ * Depends on {@link ReportingServicePort} for:
+ * - Index and state access
+ * - Cost and analytics data
+ * - PR monitor integration
+ * - Collision detection
+ *
+ * ## Key Methods
+ * - `reportDashboard()` - generate global dashboard
+ * - `reportFeatureSummary()` - generate per-feature summary
+ * - `collisionsScan()` - detect collisions across features
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - feature state or index missing
+ *
+ * @example
+ * ```typescript
+ * const reportingService = new ReportingService(port);
+ * const dashboard = await reportingService.reportDashboard();
+ * const summary = await reportingService.reportFeatureSummary('my_feature');
+ * ```
+ *
+ * ## Dashboard Contents
+ * - Active/blocked/merged feature counts
+ * - Lock ownership
+ * - Runtime session metadata
+ * - Cost analytics
+ * - PR status (if integrated)
+ */
 export declare class ReportingService {
     private readonly port;
     constructor(port: ReportingServicePort);
+    /**
+     * Detects collisions across all accepted plans.
+     *
+     * @returns Collision matrix with conflicts by feature
+     *
+     * @example
+     * ```typescript
+     * const collisions = await reportingService.collisionsScan();
+     * console.log(collisions.data.has_collisions);
+     * ```
+     */
     collisionsScan(): Promise<{
         data: {
             collisions: any[];
         };
     }>;
+    /**
+     * Generates global orchestration dashboard.
+     *
+     * @returns Dashboard with active/blocked/merged features, locks, costs, PR metadata
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await reportingService.reportDashboard();
+     * console.log(dashboard.data.active);
+     * console.log(dashboard.data.locks);
+     * ```
+     */
     reportDashboard(): Promise<{
         data: {
             index: AnyRecord;
             features: any[];
         };
     }>;
+    /**
+     * Generates per-feature summary report.
+     *
+     * @param featureId - feature identifier
+     * @returns Feature summary with state, diff, evidence, costs, QA index
+     * @throws FILE_NOT_FOUND - feature does not exist
+     *
+     * @example
+     * ```typescript
+     * const summary = await reportingService.reportFeatureSummary('my_feature');
+     * console.log(summary.data.state);
+     * console.log(summary.data.diff);
+     * ```
+     */
     reportFeatureSummary(featureId: string | null): Promise<{
         data: {
             feature_id: string;

package/dist/apps/control-plane/application/services/reporting-service.js

@@ -11,11 +11,60 @@ function readHeldLocks(frontMatter) {
 function createCollisionFingerprint(collisions) {
     return stableHash(JSON.stringify(collisions));
 }
+/**
+ * Manages dashboard and feature summary generation.
+ *
+ * ## Responsibilities
+ * - Generate report.dashboard with global index snapshot
+ * - Generate report.feature_summary with per-feature details
+ * - Aggregate cost and PR metadata
+ * - Provide gate profile summaries
+ *
+ * ## Dependencies
+ * Depends on {@link ReportingServicePort} for:
+ * - Index and state access
+ * - Cost and analytics data
+ * - PR monitor integration
+ * - Collision detection
+ *
+ * ## Key Methods
+ * - `reportDashboard()` - generate global dashboard
+ * - `reportFeatureSummary()` - generate per-feature summary
+ * - `collisionsScan()` - detect collisions across features
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - feature state or index missing
+ *
+ * @example
+ * ```typescript
+ * const reportingService = new ReportingService(port);
+ * const dashboard = await reportingService.reportDashboard();
+ * const summary = await reportingService.reportFeatureSummary('my_feature');
+ * ```
+ *
+ * ## Dashboard Contents
+ * - Active/blocked/merged feature counts
+ * - Lock ownership
+ * - Runtime session metadata
+ * - Cost analytics
+ * - PR status (if integrated)
+ */
 export class ReportingService {
     port;
     constructor(port) {
         this.port = port;
     }
+    /**
+     * Detects collisions across all accepted plans.
+     *
+     * @returns Collision matrix with conflicts by feature
+     *
+     * @example
+     * ```typescript
+     * const collisions = await reportingService.collisionsScan();
+     * console.log(collisions.data.has_collisions);
+     * ```
+     */
     async collisionsScan() {
         const plans = await this.port.collectAcceptedPlans();
         const matrix = [];
@@ -40,6 +89,18 @@ export class ReportingService {
             },
         };
     }
+    /**
+     * Generates global orchestration dashboard.
+     *
+     * @returns Dashboard with active/blocked/merged features, locks, costs, PR metadata
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await reportingService.reportDashboard();
+     * console.log(dashboard.data.active);
+     * console.log(dashboard.data.locks);
+     * ```
+     */
     async reportDashboard() {
         const index = await this.port.readIndex();
         const featureIds = normalizeSet([
@@ -84,6 +145,20 @@ export class ReportingService {
             },
         };
     }
+    /**
+     * Generates per-feature summary report.
+     *
+     * @param featureId - feature identifier
+     * @returns Feature summary with state, diff, evidence, costs, QA index
+     * @throws FILE_NOT_FOUND - feature does not exist
+     *
+     * @example
+     * ```typescript
+     * const summary = await reportingService.reportFeatureSummary('my_feature');
+     * console.log(summary.data.state);
+     * console.log(summary.data.diff);
+     * ```
+     */
     async reportFeatureSummary(featureId) {
         const state = await this.port.featureStateGet(featureId);
         const bundle = await this.port.repoDiffBundle(featureId);

package/dist/apps/control-plane/application/services/reporting-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"reporting-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/reporting-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reporting-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/reporting-service.ts"],"names":[],"mappings":"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"}

package/dist/apps/control-plane/application/services/run-lease-service.d.ts

@@ -32,9 +32,64 @@ export interface RunLeaseServicePort {
     isRunLeaseFresh(runtimeSessions: RuntimeSessionsSnapshot): boolean;
     emptyRuntimeSessions(at?: string): RuntimeSessionsSnapshot;
 }
+/**
+ * Manages run lease acquisition, renewal, and release.
+ *
+ * ## Responsibilities
+ * - Acquire exclusive run lease for orchestrator instance
+ * - Renew lease heartbeat to prevent staleness
+ * - Release lease on shutdown
+ * - Track orchestrator and feature session assignments
+ * - Prune stale session assignments
+ *
+ * ## Dependencies
+ * Depends on {@link RunLeaseServicePort} for:
+ * - Run lease file operations
+ * - Index operations
+ * - Lease TTL configuration
+ *
+ * ## Key Methods
+ * - `acquireRunLease()` - acquire exclusive run lease
+ * - `renewRunLease()` - renew lease heartbeat
+ * - `releaseRunLease()` - release lease
+ * - `updateOrchestratorSession()` - update orchestrator session metadata
+ * - `updateFeatureSessionAssignment()` - assign feature to sessions
+ * - `pruneFeatureSessionAssignments()` - remove stale assignments
+ *
+ * ## Error Conditions
+ * - RUN_ALREADY_ACTIVE - another instance holds fresh lease
+ * - STALE_LEASE - lease expired (can be taken over)
+ *
+ * @example
+ * ```typescript
+ * const leaseService = new RunLeaseService(port);
+ * const lease = await leaseService.acquireRunLease({
+ *   run_id: 'run_123',
+ *   owner_instance_id: 'instance_abc',
+ *   takeover_stale: false
+ * });
+ * await leaseService.renewRunLease(lease.data.run_id, lease.data.owner_instance_id);
+ * ```
+ */
 export declare class RunLeaseService {
     private readonly port;
     constructor(port: RunLeaseServicePort);
+    /**
+     * Acquires exclusive run lease for orchestrator instance.
+     *
+     * @param input - acquisition parameters (run_id, owner_instance_id, takeover_stale)
+     * @returns Lease acquisition result
+     * @throws RUN_ALREADY_ACTIVE - another instance holds fresh lease
+     *
+     * @example
+     * ```typescript
+     * const lease = await leaseService.acquireRunLease({
+     *   run_id: 'run_123',
+     *   owner_instance_id: 'instance_abc',
+     *   takeover_stale: false
+     * });
+     * ```
+     */
     acquireRunLease(input: AcquireRunLeaseInput): Promise<{
         data: {
             runtime_sessions: RuntimeSessionsSnapshot;
@@ -42,11 +97,35 @@ export declare class RunLeaseService {
             reused_existing_owner: boolean;
         };
     }>;
+    /**
+     * Renews run lease heartbeat to prevent staleness.
+     *
+     * @param runId - run identifier
+     * @param ownerInstanceId - instance identifier
+     * @returns Renewal result
+     *
+     * @example
+     * ```typescript
+     * await leaseService.renewRunLease('run_123', 'instance_abc');
+     * ```
+     */
     renewRunLease(runId: string, ownerInstanceId: string): Promise<{
         data: {
             lease_expires_at: string;
         };
     }>;
+    /**
+     * Releases run lease on shutdown.
+     *
+     * @param runId - run identifier
+     * @param ownerInstanceId - instance identifier
+     * @returns Release result
+     *
+     * @example
+     * ```typescript
+     * await leaseService.releaseRunLease('run_123', 'instance_abc');
+     * ```
+     */
     releaseRunLease(runId: string, ownerInstanceId: string): Promise<{
         data: {
             released: boolean;