Implemented operations helper commands for validation, locking, and status

2026-05-21 11:50:20 -05:00
parent a813bd5a50
commit 228c348e42
19 changed files with 1653 additions and 408 deletions
--- a/internal/app/commands.go
+++ b/internal/app/commands.go
@@ -7,7 +7,7 @@ import (
 	"strings"
 )

-var supportedCommands = []string{"run", "plan", "status", "resume", "run-stage", "restore"}
+var supportedCommands = []string{"run", "plan", "status", "resume", "run-stage", "restore", "session", "artifacts", "locks", "lock", "unlock"}

 // Execute dispatches CLI commands and returns a process exit code.
 func Execute(args []string, stdout, stderr io.Writer) int {
@@ -34,6 +34,16 @@ func Execute(args []string, stdout, stderr io.Writer) int {
 		err = RunStage(ctx, cmdArgs, stdout)
 	case "restore":
 		err = Restore(ctx, cmdArgs, stdout)
+	case "session":
+		err = Session(ctx, cmdArgs, stdout)
+	case "artifacts":
+		err = Artifacts(ctx, cmdArgs, stdout)
+	case "locks":
+		err = Locks(ctx, cmdArgs, stdout)
+	case "lock":
+		err = Lock(ctx, cmdArgs, stdout)
+	case "unlock":
+		err = Unlock(ctx, cmdArgs, stdout)
 	default:
 		fmt.Fprintf(stderr, "unknown command: %q\n\n", cmd)
 		printUsage(stderr)
--- a/internal/app/operator_helpers.go
+++ b/internal/app/operator_helpers.go
@@ -0,0 +1,870 @@
+package app
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gopkg.in/yaml.v3"
+)
+
+type commonConfigFlags struct {
+	pipelinePath      string
+	campaignPath      string
+	sessionPath       string
+	sessionID         string
+	previousSessionID string
+}
+
+type finding struct {
+	Severity string
+	Category string
+	Message  string
+}
+
+type findingError struct {
+	count int
+}
+
+func (e findingError) Error() string {
+	return fmt.Sprintf("%d validation error(s)", e.count)
+}
+
+func addCommonConfigFlags(fs *flag.FlagSet, flags *commonConfigFlags) {
+	fs.StringVar(&flags.pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
+	fs.StringVar(&flags.campaignPath, "campaign", "", "path to campaign.yml (optional; defaults searched)")
+	fs.StringVar(&flags.sessionPath, "session", "", "path to session.yml")
+	fs.StringVar(&flags.sessionID, "session-id", "", "session identifier for session.yml templates")
+	fs.StringVar(&flags.previousSessionID, "previous-session-id", "", "previous session identifier for session.yml templates")
+}
+
+func (f commonConfigFlags) sessionOptions() config.SessionLoadOptions {
+	return config.SessionLoadOptions{
+		SessionID:         f.sessionID,
+		PreviousSessionID: f.previousSessionID,
+	}
+}
+
+// Session dispatches session helper subcommands.
+func Session(ctx context.Context, args []string, out io.Writer) error {
+	if len(args) == 0 {
+		return fmt.Errorf("session: expected subcommand: validate|init")
+	}
+	switch args[0] {
+	case "validate":
+		return SessionValidate(ctx, args[1:], out)
+	case "init":
+		return SessionInit(ctx, args[1:], out)
+	default:
+		return fmt.Errorf("session: unknown subcommand %q", args[0])
+	}
+}
+
+// Artifacts dispatches artifact helper subcommands.
+func Artifacts(ctx context.Context, args []string, out io.Writer) error {
+	if len(args) == 0 {
+		return fmt.Errorf("artifacts: expected subcommand: list")
+	}
+	switch args[0] {
+	case "list":
+		return ArtifactsList(ctx, args[1:], out)
+	default:
+		return fmt.Errorf("artifacts: unknown subcommand %q", args[0])
+	}
+}
+
+// SessionValidate performs a read-only session preflight.
+func SessionValidate(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("session validate", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	addCommonConfigFlags(fs, &flags)
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("session validate: invalid flags: %w", err)
+	}
+	if fs.NArg() != 0 {
+		return fmt.Errorf("session validate: unexpected positional arguments")
+	}
+
+	findings := []finding{}
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.sessionPath, flags.sessionOptions())
+	if err != nil {
+		findings = append(findings, errorFinding("config", err.Error()))
+		return renderFindings(out, "", "", findings)
+	}
+	if err := config.Validate(cfg); err != nil {
+		findings = append(findings, errorFinding("config", err.Error()))
+	} else {
+		findings = append(findings, okFinding("config", "resolved pipeline, campaign, and session config"))
+	}
+	findings = append(findings, okFinding("session", fmt.Sprintf("session source: %s", sessionSourceSummary(cfg))))
+
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	findings = append(findings, validateStableInputFindings(cfg)...)
+	findings = append(findings, validateLocalAudioFindings(cfg)...)
+
+	store, storeErr := objectStoreIfConfigured(ctx, cfg)
+	if storeErr != nil {
+		findings = append(findings, errorFinding("storage", storeErr.Error()))
+	}
+	if cfg.Session.Inputs.AudioS3 != nil {
+		if storeErr != nil {
+			findings = append(findings, errorFinding("audio", "remote audio cannot be checked because storage is unavailable"))
+		} else {
+			findings = append(findings, validateRemoteAudioFinding(ctx, cfg, store))
+		}
+	}
+
+	requirements := artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg))
+	if len(requirements) == 0 {
+		findings = append(findings, okFinding("previous", "no previous-session artifacts required"))
+	} else if strings.TrimSpace(cfg.Session.PreviousSessionID) == "" {
+		findings = append(findings, errorFinding("previous", "previous_session_id is required by configured previous-session artifacts"))
+	} else if storeErr != nil {
+		findings = append(findings, errorFinding("previous", "previous-session artifacts cannot be checked because storage is unavailable"))
+	} else {
+		findings = append(findings, validatePreviousArtifactFindings(ctx, cfg, store, requirements)...)
+	}
+
+	locks, lockErr := loadEffectiveLocks(ctx, cfg, store)
+	if lockErr != nil {
+		findings = append(findings, errorFinding("locks", lockErr.Error()))
+	} else if len(locks.All) == 0 {
+		findings = append(findings, okFinding("locks", "no effective archive locks"))
+	} else {
+		for _, lock := range locks.All {
+			findings = append(findings, warnFinding("locks", fmt.Sprintf("%s locked: %s", lock.Source, strings.TrimSpace(lock.Reason))))
+		}
+	}
+	if paths.ManifestPath != "" {
+		findings = append(findings, infoFinding("workspace", "manifest path: "+paths.ManifestPath))
+	}
+	return renderFindings(out, cfg.Session.Campaign, cfg.Session.SessionID, findings)
+}
+
+// Status reports either a requested manifest or effective local/remote session state.
+func Status(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("status", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var manifestPath string
+	var flags commonConfigFlags
+	fs.StringVar(&manifestPath, "manifest", "", "path to manifest.json")
+	addCommonConfigFlags(fs, &flags)
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("status: invalid flags: %w", err)
+	}
+	if fs.NArg() != 0 {
+		return fmt.Errorf("status: unexpected positional arguments")
+	}
+	if strings.TrimSpace(manifestPath) != "" {
+		return statusManifest(ctx, manifestPath, out)
+	}
+	if flags.pipelinePath == "" && flags.campaignPath == "" && flags.sessionPath == "" && flags.sessionID == "" && flags.previousSessionID == "" {
+		return fmt.Errorf("status: --manifest is required")
+	}
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.sessionPath, flags.sessionOptions())
+	if err != nil {
+		return fmt.Errorf("status: %w", err)
+	}
+	if err := config.Validate(cfg); err != nil {
+		return fmt.Errorf("status: %w", err)
+	}
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	fmt.Fprintf(out, "Session: %s\n", cfg.Session.SessionID)
+	fmt.Fprintf(out, "Campaign: %s\n", cfg.Session.Campaign)
+	fmt.Fprintf(out, "Workspace: %s\n", paths.Root)
+	fmt.Fprintf(out, "Session config: %s\n", sessionSourceSummary(cfg))
+
+	if m, err := loadLocalManifest(ctx, paths.ManifestPath); err != nil {
+		fmt.Fprintf(out, "Local manifest: error: %v\n", err)
+	} else if m == nil {
+		fmt.Fprintln(out, "Local manifest: missing")
+	} else {
+		fmt.Fprintf(out, "Local manifest: %s\n", paths.ManifestPath)
+		writeStageStatuses(out, m)
+	}
+
+	store, storeErr := objectStoreIfConfigured(ctx, cfg)
+	if storeErr != nil {
+		fmt.Fprintf(out, "Remote archive: unavailable: %v\n", storeErr)
+	} else if store != nil {
+		current, err := discoverRemoteCurrentStateFn(ctx, cfg, store)
+		if err != nil {
+			fmt.Fprintf(out, "Remote archive: missing or unavailable: %v\n", err)
+		} else {
+			fmt.Fprintf(out, "Remote archive: current run %s\n", current.RunID)
+			fmt.Fprintf(out, "Remote manifest: %s\n", current.CurrentManifestKey)
+		}
+	}
+
+	locks, err := loadEffectiveLocks(ctx, cfg, store)
+	if err != nil {
+		fmt.Fprintf(out, "Archive locks: error: %v\n", err)
+	} else {
+		writeLocks(out, cfg, locks)
+	}
+	fmt.Fprintln(out, "Next actions:")
+	fmt.Fprintf(out, "- narratio session validate --session-id %s\n", cfg.Session.SessionID)
+	fmt.Fprintf(out, "- narratio restore --session-id %s --dry-run\n", cfg.Session.SessionID)
+	return nil
+}
+
+func statusManifest(ctx context.Context, manifestPath string, out io.Writer) error {
+	store := &manifest.LocalStore{}
+	m, err := store.Load(ctx, manifestPath)
+	if err != nil {
+		return fmt.Errorf("status: %w", err)
+	}
+	if _, err := fmt.Fprintf(out, "session_id: %s\n", m.SessionID); err != nil {
+		return err
+	}
+	if _, err := fmt.Fprintf(out, "updated_at: %s\n", m.UpdatedAt.UTC().Format("2006-01-02T15:04:05Z07:00")); err != nil {
+		return err
+	}
+	writeStageStatuses(out, m)
+	return nil
+}
+
+// SessionInit creates a local or remote session.yml skeleton.
+func SessionInit(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("session init", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var pipelinePath, campaignPath, sessionID, previousSessionID, date, title, output, audioS3Prefix, audioDir string
+	var remote, force bool
+	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml")
+	fs.StringVar(&campaignPath, "campaign", "", "path to campaign.yml")
+	fs.StringVar(&sessionID, "session-id", "", "session identifier")
+	fs.StringVar(&previousSessionID, "previous-session-id", "", "previous session identifier")
+	fs.StringVar(&date, "date", "", "session date")
+	fs.StringVar(&title, "title", "", "session title")
+	fs.StringVar(&output, "output", "", "local output session.yml path")
+	fs.StringVar(&audioS3Prefix, "audio-s3-prefix", "", "session audio S3 prefix")
+	fs.StringVar(&audioDir, "audio-dir", "", "local audio directory")
+	fs.BoolVar(&remote, "remote", false, "write session.yml to S3 session prefix")
+	fs.BoolVar(&force, "force", false, "overwrite existing target")
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("session init: invalid flags: %w", err)
+	}
+	if fs.NArg() != 0 {
+		return fmt.Errorf("session init: unexpected positional arguments")
+	}
+	if strings.TrimSpace(pipelinePath) == "" || strings.TrimSpace(campaignPath) == "" || strings.TrimSpace(sessionID) == "" {
+		return fmt.Errorf("session init: --config, --campaign, and --session-id are required")
+	}
+	if (strings.TrimSpace(output) == "") == !remote {
+		return fmt.Errorf("session init: specify exactly one target: --output <path> or --remote")
+	}
+	if strings.TrimSpace(audioDir) != "" && strings.TrimSpace(audioS3Prefix) != "" {
+		return fmt.Errorf("session init: --audio-dir and --audio-s3-prefix are mutually exclusive")
+	}
+
+	resolvedPipeline, err := resolvePipelineConfigPath(pipelinePath)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	resolvedCampaign, err := resolveCampaignConfigPath(campaignPath)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	pipelineCfg, err := config.LoadPipeline(resolvedPipeline)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	campaignCfg, err := config.LoadCampaign(resolvedCampaign)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+
+	data, err := buildSessionYAML(campaignCfg.Campaign, sessionID, previousSessionID, date, title, audioS3Prefix, audioDir)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	label := strings.TrimSpace(output)
+	if label == "" {
+		label = "remote session.yml"
+	}
+	sessionCfg, err := config.LoadSessionBytesWithOptions(label, data, config.SessionLoadOptions{
+		SessionID:         sessionID,
+		PreviousSessionID: previousSessionID,
+	})
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	cfg, err := config.Resolve(resolvedPipeline, pipelineCfg, resolvedCampaign, campaignCfg, label, sessionCfg, config.SessionSource{Source: "session_config", LocalPath: label})
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	if err := config.Validate(cfg); err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+
+	if !remote {
+		if err := writeLocalFile(output, data, force); err != nil {
+			return fmt.Errorf("session init: %w", err)
+		}
+		_, err := fmt.Fprintf(out, "narratio session init: wrote %s\n", filepath.Clean(output))
+		return err
+	}
+
+	store, err := newObjectStoreFromConfigFn(ctx, cfg)
+	if err != nil {
+		return fmt.Errorf("session init: %w", err)
+	}
+	sessionPrefix := artifacts.S3SessionPrefix(pipelineCfg.Storage.S3.RootPrefix, campaignCfg.Campaign, sessionID)
+	key := artifacts.S3SessionConfigKey(sessionPrefix)
+	exists, err := store.Exists(ctx, key)
+	if err != nil {
+		return fmt.Errorf("session init: check remote session %q: %w", key, err)
+	}
+	if exists && !force {
+		return fmt.Errorf("session init: remote session %q already exists; pass --force to overwrite", key)
+	}
+	tmp, err := os.CreateTemp("", "narratio-session-init-*.yml")
+	if err != nil {
+		return fmt.Errorf("session init: create temp file: %w", err)
+	}
+	tmpPath := tmp.Name()
+	defer func() { _ = os.Remove(tmpPath) }()
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("session init: write temp file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("session init: close temp file: %w", err)
+	}
+	if _, err := store.Upload(ctx, tmpPath, key, storage.UploadOptions{ContentType: "application/x-yaml; charset=utf-8"}); err != nil {
+		return fmt.Errorf("session init: upload remote session %q: %w", key, err)
+	}
+	_, err = fmt.Fprintf(out, "narratio session init: wrote s3://%s/%s\n", s3BucketName(pipelineCfg), key)
+	return err
+}
+
+// ArtifactsList lists effective artifact sources.
+func ArtifactsList(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("artifacts list", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	var remote bool
+	addCommonConfigFlags(fs, &flags)
+	fs.BoolVar(&remote, "remote", false, "inspect remote archive availability")
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("artifacts list: invalid flags: %w", err)
+	}
+	if fs.NArg() != 0 {
+		return fmt.Errorf("artifacts list: unexpected positional arguments")
+	}
+	cfg, store, locks, _, err := loadHelperContext(ctx, flags, remote)
+	if err != nil {
+		return fmt.Errorf("artifacts list: %w", err)
+	}
+	catalog, err := buildHelperArtifactCatalog(cfg)
+	if err != nil {
+		return fmt.Errorf("artifacts list: %w", err)
+	}
+	remoteState := map[string]string{}
+	if remote && store != nil {
+		remoteState = remoteArtifactAvailability(ctx, cfg, store, catalog)
+	}
+	writeArtifactList(out, cfg, catalog, locks, remoteState)
+	return nil
+}
+
+// Locks lists effective archive locks.
+func Locks(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("locks", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	addCommonConfigFlags(fs, &flags)
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("locks: invalid flags: %w", err)
+	}
+	if fs.NArg() != 0 {
+		return fmt.Errorf("locks: unexpected positional arguments")
+	}
+	cfg, _, locks, _, err := loadHelperContext(ctx, flags, true)
+	if err != nil {
+		return fmt.Errorf("locks: %w", err)
+	}
+	writeLocks(out, cfg, locks)
+	return nil
+}
+
+// Lock adds or updates one remote lock.
+func Lock(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("lock", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	var reason string
+	var force bool
+	addCommonConfigFlags(fs, &flags)
+	fs.StringVar(&reason, "reason", "", "lock reason")
+	fs.BoolVar(&force, "force", false, "update existing remote lock")
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("lock: invalid flags: %w", err)
+	}
+	if fs.NArg() != 1 {
+		return fmt.Errorf("lock: expected exactly one source id")
+	}
+	source := strings.TrimSpace(fs.Arg(0))
+	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
+	if err != nil {
+		return fmt.Errorf("lock: %w", err)
+	}
+	if _, err := config.ValidateArchiveLockRules([]config.ArchiveLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, "lock"); err != nil {
+		return fmt.Errorf("lock: %w", err)
+	}
+	if _, ok := lockSourceSet(locks.Static)[source]; ok {
+		return fmt.Errorf("lock: source %q is locked by pipeline config and cannot be modified remotely", source)
+	}
+	remoteSet := lockSourceSet(locks.Remote)
+	if _, exists := remoteSet[source]; exists && !force {
+		return fmt.Errorf("lock: remote lock for %q already exists; pass --force to update", source)
+	}
+	remoteSet[source] = config.ArchiveLockRule{Source: source, Reason: strings.TrimSpace(reason)}
+	remoteLocks := lockMapValues(remoteSet)
+	if _, err := config.ValidateArchiveLockRules(remoteLocks, cfg.Pipeline.Scriptorium, "locks"); err != nil {
+		return fmt.Errorf("lock: %w", err)
+	}
+	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.ArchiveLockStore{Locks: remoteLocks}); err != nil {
+		return fmt.Errorf("lock: %w", err)
+	}
+	_, err = fmt.Fprintf(out, "narratio lock: locked %s\n", source)
+	return err
+}
+
+// Unlock removes one remote lock.
+func Unlock(ctx context.Context, args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("unlock", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	var flags commonConfigFlags
+	addCommonConfigFlags(fs, &flags)
+	if err := fs.Parse(args); err != nil {
+		return fmt.Errorf("unlock: invalid flags: %w", err)
+	}
+	if fs.NArg() != 1 {
+		return fmt.Errorf("unlock: expected exactly one source id")
+	}
+	source := strings.TrimSpace(fs.Arg(0))
+	cfg, store, locks, _, err := loadHelperContext(ctx, flags, true)
+	if err != nil {
+		return fmt.Errorf("unlock: %w", err)
+	}
+	if _, err := config.ValidateArchiveLockRules([]config.ArchiveLockRule{{Source: source}}, cfg.Pipeline.Scriptorium, "unlock"); err != nil {
+		return fmt.Errorf("unlock: %w", err)
+	}
+	remoteSet := lockSourceSet(locks.Remote)
+	if _, ok := remoteSet[source]; !ok {
+		if _, static := lockSourceSet(locks.Static)[source]; static {
+			return fmt.Errorf("unlock: source %q is locked by pipeline config and cannot be unlocked remotely", source)
+		}
+		return fmt.Errorf("unlock: remote lock for %q does not exist", source)
+	}
+	delete(remoteSet, source)
+	remoteLocks := lockMapValues(remoteSet)
+	if err := uploadRemoteLockStore(ctx, store, locks.Key, &config.ArchiveLockStore{Locks: remoteLocks}); err != nil {
+		return fmt.Errorf("unlock: %w", err)
+	}
+	_, err = fmt.Fprintf(out, "narratio unlock: unlocked %s\n", source)
+	return err
+}
+
+func loadHelperContext(ctx context.Context, flags commonConfigFlags, needStore bool) (*config.Config, storage.ObjectStore, *effectiveLocks, *manifest.Manifest, error) {
+	cfg, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.sessionPath, flags.sessionOptions())
+	if err != nil {
+		return nil, nil, nil, nil, err
+	}
+	if err := config.Validate(cfg); err != nil {
+		return nil, nil, nil, nil, err
+	}
+	var store storage.ObjectStore
+	if needStore {
+		store, err = newObjectStoreFromConfigFn(ctx, cfg)
+		if err != nil {
+			return nil, nil, nil, nil, err
+		}
+	} else {
+		store, _ = objectStoreIfConfigured(ctx, cfg)
+	}
+	locks, err := loadEffectiveLocks(ctx, cfg, store)
+	if err != nil {
+		return nil, nil, nil, nil, err
+	}
+	paths := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).SessionPathsFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	m, err := loadLocalManifest(ctx, paths.ManifestPath)
+	if err != nil {
+		return nil, nil, nil, nil, err
+	}
+	return cfg, store, locks, m, nil
+}
+
+func objectStoreIfConfigured(ctx context.Context, cfg *config.Config) (storage.ObjectStore, error) {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Storage.S3 == nil || strings.TrimSpace(cfg.Pipeline.Storage.S3.Bucket) == "" {
+		return nil, nil
+	}
+	store, err := newObjectStoreFromConfigFn(ctx, cfg)
+	if err != nil {
+		return nil, err
+	}
+	return store, nil
+}
+
+func buildSessionYAML(campaign, sessionID, previousSessionID, date, title, audioS3Prefix, audioDir string) ([]byte, error) {
+	if strings.TrimSpace(date) == "" && regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`).MatchString(strings.TrimSpace(sessionID)) {
+		date = strings.TrimSpace(sessionID)
+	}
+	type audioS3 struct {
+		Prefix string `yaml:"prefix"`
+	}
+	type inputs struct {
+		AudioDir string   `yaml:"audio_dir,omitempty"`
+		AudioS3  *audioS3 `yaml:"audio_s3,omitempty"`
+	}
+	type sessionYAML struct {
+		Campaign          string `yaml:"campaign"`
+		SessionID         string `yaml:"session_id"`
+		PreviousSessionID string `yaml:"previous_session_id,omitempty"`
+		Date              string `yaml:"date,omitempty"`
+		Title             string `yaml:"title,omitempty"`
+		Inputs            inputs `yaml:"inputs"`
+	}
+	in := inputs{AudioDir: strings.TrimSpace(audioDir)}
+	if in.AudioDir == "" {
+		prefix := strings.TrimSpace(audioS3Prefix)
+		if prefix == "" {
+			prefix = "audio/"
+		}
+		in.AudioS3 = &audioS3{Prefix: prefix}
+	}
+	data, err := yaml.Marshal(sessionYAML{
+		Campaign:          strings.TrimSpace(campaign),
+		SessionID:         strings.TrimSpace(sessionID),
+		PreviousSessionID: strings.TrimSpace(previousSessionID),
+		Date:              strings.TrimSpace(date),
+		Title:             strings.TrimSpace(title),
+		Inputs:            in,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return data, nil
+}
+
+func renderFindings(out io.Writer, campaign, sessionID string, findings []finding) error {
+	if campaign != "" || sessionID != "" {
+		fmt.Fprintf(out, "Campaign: %s\n", campaign)
+		fmt.Fprintf(out, "Session: %s\n\n", sessionID)
+	}
+	errorsCount := 0
+	for _, f := range findings {
+		if f.Severity == "ERROR" {
+			errorsCount++
+		}
+		fmt.Fprintf(out, "%-5s %-10s %s\n", f.Severity, f.Category, f.Message)
+	}
+	if errorsCount > 0 {
+		return findingError{count: errorsCount}
+	}
+	return nil
+}
+
+func okFinding(category, msg string) finding    { return finding{"OK", category, msg} }
+func infoFinding(category, msg string) finding  { return finding{"INFO", category, msg} }
+func warnFinding(category, msg string) finding  { return finding{"WARN", category, msg} }
+func errorFinding(category, msg string) finding { return finding{"ERROR", category, msg} }
+
+func sessionSourceSummary(cfg *config.Config) string {
+	source := cfg.SessionSource.Source
+	if source == "" {
+		source = "session_config"
+	}
+	if cfg.SessionSource.S3Key != "" {
+		return source + " " + cfg.SessionSource.S3Key
+	}
+	return source + " " + cfg.SessionPath
+}
+
+func validateStableInputFindings(cfg *config.Config) []finding {
+	items := []struct {
+		name string
+		in   config.ResolvedInputFile
+	}{
+		{"speakers", cfg.StableInputs.SpeakersFile},
+		{"autocorrect", cfg.StableInputs.AutocorrectFile},
+		{"glossary", cfg.StableInputs.GlossaryFile},
+	}
+	out := make([]finding, 0, len(items))
+	for _, item := range items {
+		path, err := resolveHelperConfigRelativePath(item.in)
+		if err != nil {
+			out = append(out, errorFinding("inputs", item.name+": "+err.Error()))
+			continue
+		}
+		if _, err := os.Stat(path); err != nil {
+			out = append(out, errorFinding("inputs", fmt.Sprintf("%s missing: %v", item.name, err)))
+		} else {
+			out = append(out, okFinding("inputs", item.name+": "+path))
+		}
+	}
+	return out
+}
+
+func resolveHelperConfigRelativePath(input config.ResolvedInputFile) (string, error) {
+	if strings.TrimSpace(input.ConfigPath) == "" {
+		return "", fmt.Errorf("source config path is required")
+	}
+	path := strings.TrimSpace(input.Path)
+	if path == "" {
+		return "", fmt.Errorf("path is required")
+	}
+	if filepath.IsAbs(path) {
+		return filepath.Clean(path), nil
+	}
+	return filepath.Clean(filepath.Join(filepath.Dir(input.ConfigPath), path)), nil
+}
+
+func validateLocalAudioFindings(cfg *config.Config) []finding {
+	if cfg.Session.Inputs.AudioS3 != nil {
+		return nil
+	}
+	audioDir := strings.TrimSpace(cfg.Session.Inputs.AudioDir)
+	if audioDir == "" && len(cfg.Session.Inputs.AudioFiles) == 0 {
+		return []finding{errorFinding("audio", "audio_dir, audio_files, or audio_s3 is required")}
+	}
+	base := filepath.Dir(cfg.SessionPath)
+	paths := []string{}
+	if audioDir != "" {
+		dir := audioDir
+		if !filepath.IsAbs(dir) {
+			dir = filepath.Join(base, dir)
+		}
+		matches, err := filepath.Glob(filepath.Join(dir, "*.flac"))
+		if err != nil || len(matches) == 0 {
+			return []finding{errorFinding("audio", "no .flac files found in "+dir)}
+		}
+		paths = append(paths, matches...)
+	}
+	for _, file := range cfg.Session.Inputs.AudioFiles {
+		p := file
+		if !filepath.IsAbs(p) {
+			p = filepath.Join(base, p)
+		}
+		paths = append(paths, p)
+	}
+	for _, p := range paths {
+		if _, err := os.Stat(p); err != nil {
+			return []finding{errorFinding("audio", fmt.Sprintf("audio file missing: %v", err))}
+		}
+	}
+	return []finding{okFinding("audio", fmt.Sprintf("%d local audio file(s)", len(paths)))}
+}
+
+func validateRemoteAudioFinding(ctx context.Context, cfg *config.Config, store storage.ObjectStore) finding {
+	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
+	audioPrefix := artifacts.S3AudioPrefix(sessionPrefix, cfg.Session.Inputs.AudioS3.Prefix)
+	objects, err := store.List(ctx, audioPrefix)
+	if err != nil {
+		return errorFinding("audio", err.Error())
+	}
+	count := 0
+	for _, obj := range objects {
+		if strings.HasSuffix(strings.ToLower(obj.Key), ".flac") {
+			count++
+		}
+	}
+	if count == 0 {
+		return errorFinding("audio", "no remote .flac objects found under "+audioPrefix)
+	}
+	return okFinding("audio", fmt.Sprintf("%d remote .flac object(s)", count))
+}
+
+func validatePreviousArtifactFindings(ctx context.Context, cfg *config.Config, store storage.ObjectStore, requirements []artifacts.PreviousArtifactRequirement) []finding {
+	out := []finding{}
+	prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
+	manifestKey, runIDKey := artifacts.ResolveArchiveCurrentStateKeys(prefix)
+	for _, key := range []string{runIDKey, manifestKey} {
+		exists, err := store.Exists(ctx, key)
+		if err != nil {
+			out = append(out, errorFinding("previous", fmt.Sprintf("check %s: %v", key, err)))
+			return out
+		}
+		if !exists {
+			out = append(out, errorFinding("previous", "missing "+key))
+			return out
+		}
+	}
+	for _, req := range requirements {
+		out = append(out, okFinding("previous", fmt.Sprintf("%s required=%t", req.Name, req.Required)))
+	}
+	return out
+}
+
+func loadLocalManifest(ctx context.Context, path string) (*manifest.Manifest, error) {
+	if _, err := os.Stat(path); err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	store := &manifest.LocalStore{}
+	return store.Load(ctx, path)
+}
+
+func writeStageStatuses(out io.Writer, m *manifest.Manifest) {
+	if m == nil || len(m.Stages) == 0 {
+		fmt.Fprintln(out, "stages: no stages recorded")
+		return
+	}
+	fmt.Fprintln(out, "stages:")
+	names := make([]string, 0, len(m.Stages))
+	for name := range m.Stages {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		fmt.Fprintf(out, "- %s: %s\n", name, m.Stages[name].Status)
+	}
+}
+
+func buildHelperArtifactCatalog(cfg *config.Config) (*artifacts.ArtifactCatalog, error) {
+	catalog := artifacts.NewArtifactCatalog()
+	if err := catalog.RegisterBuiltIns(); err != nil {
+		return nil, err
+	}
+	configured := map[string]artifacts.ConfiguredArtifactDefinition{}
+	if cfg.Pipeline.Scriptorium != nil {
+		for key, item := range cfg.Pipeline.Scriptorium.Artifacts {
+			configured[key] = artifacts.ConfiguredArtifactDefinition{Enabled: item.Enabled, OutputPath: item.OutputPath}
+		}
+	}
+	if err := catalog.RegisterConfiguredArtifacts(configured, nil); err != nil {
+		return nil, err
+	}
+	return catalog, nil
+}
+
+func writeArtifactList(out io.Writer, cfg *config.Config, catalog *artifacts.ArtifactCatalog, locks *effectiveLocks, remoteState map[string]string) {
+	lockSet := lockSourceSet(locks.All)
+	fmt.Fprintln(out, "Built-in:")
+	for _, id := range []string{
+		artifacts.ArtifactTranscriptMerged,
+		artifacts.ArtifactTranscriptPolished,
+		artifacts.ArtifactTranscriptFull,
+		artifacts.ArtifactTranscriptTrimmed,
+		artifacts.ArtifactBoundsSession,
+	} {
+		writeArtifactLine(out, id, lockSet, remoteState)
+	}
+	fmt.Fprintln(out, "Configured:")
+	for _, entry := range catalog.ListConfigured() {
+		writeArtifactLine(out, entry.SourceID, lockSet, remoteState)
+	}
+	fmt.Fprintln(out, "Previous-session:")
+	for _, req := range artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg)) {
+		fmt.Fprintf(out, "- narratio.previous_session.artifact.%s required=%t\n", req.Name, req.Required)
+	}
+	fmt.Fprintln(out, "Promoted:")
+	for _, rule := range cfg.Pipeline.Archive.PromoteArtifacts {
+		writeArtifactLine(out, rule.Source, lockSet, remoteState)
+	}
+}
+
+func writeArtifactLine(out io.Writer, source string, lockSet map[string]config.ArchiveLockRule, remoteState map[string]string) {
+	parts := []string{source}
+	if _, ok := lockSet[source]; ok {
+		parts = append(parts, "locked")
+	}
+	if state := remoteState[source]; state != "" {
+		parts = append(parts, state)
+	}
+	fmt.Fprintf(out, "- %s\n", strings.Join(parts, " "))
+}
+
+func remoteArtifactAvailability(ctx context.Context, cfg *config.Config, store storage.ObjectStore, catalog *artifacts.ArtifactCatalog) map[string]string {
+	out := map[string]string{}
+	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
+	for _, source := range allCatalogSources(catalog) {
+		entry, ok := catalog.Lookup(source)
+		if !ok || strings.TrimSpace(entry.CanonicalRelPath) == "" {
+			continue
+		}
+		key := artifacts.S3PromotedArtifactKey(sessionPrefix, entry.CanonicalRelPath)
+		if exists, err := store.Exists(ctx, key); err == nil && exists {
+			out[source] = "remote=promoted"
+		} else if err != nil {
+			out[source] = "remote=error"
+		} else {
+			out[source] = "remote=missing"
+		}
+	}
+	return out
+}
+
+func allCatalogSources(catalog *artifacts.ArtifactCatalog) []string {
+	out := []string{
+		artifacts.ArtifactTranscriptMerged,
+		artifacts.ArtifactTranscriptPolished,
+		artifacts.ArtifactTranscriptFull,
+		artifacts.ArtifactTranscriptTrimmed,
+		artifacts.ArtifactBoundsSession,
+	}
+	for _, entry := range catalog.ListConfigured() {
+		out = append(out, entry.SourceID)
+	}
+	return out
+}
+
+func writeLocks(out io.Writer, cfg *config.Config, locks *effectiveLocks) {
+	if locks == nil || len(locks.All) == 0 {
+		fmt.Fprintln(out, "Archive locks: none")
+		return
+	}
+	fmt.Fprintln(out, "Archive locks:")
+	promoted := map[string]config.ArchivePromotionRule{}
+	if cfg != nil && cfg.Pipeline != nil && cfg.Pipeline.Archive != nil {
+		for _, rule := range cfg.Pipeline.Archive.PromoteArtifacts {
+			promoted[strings.TrimSpace(rule.Source)] = rule
+		}
+	}
+	staticSet := lockSourceSet(locks.Static)
+	for _, lock := range locks.All {
+		origin := "remote"
+		if _, ok := staticSet[lock.Source]; ok {
+			origin = "pipeline"
+		}
+		promo := "not-promoted"
+		if _, ok := promoted[lock.Source]; ok {
+			promo = "promoted"
+		}
+		reason := strings.TrimSpace(lock.Reason)
+		if reason == "" {
+			reason = "(no reason)"
+		}
+		fmt.Fprintf(out, "- %s origin=%s %s reason=%s\n", lock.Source, origin, promo, reason)
+	}
+}
+
+func lockMapValues(in map[string]config.ArchiveLockRule) []config.ArchiveLockRule {
+	keys := make([]string, 0, len(in))
+	for key := range in {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	out := make([]config.ArchiveLockRule, 0, len(keys))
+	for _, key := range keys {
+		item := in[key]
+		item.Source = key
+		item.Reason = strings.TrimSpace(item.Reason)
+		out = append(out, item)
+	}
+	return out
+}
--- a/internal/app/operator_helpers_test.go
+++ b/internal/app/operator_helpers_test.go
@@ -0,0 +1,195 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func TestExecuteSessionInitRemoteWritesCanonicalSessionConfig(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{filepath.Join(t.TempDir(), "session.yml")})
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{
+		"session", "init",
+		"--config", pipelinePath,
+		"--campaign", campaignPath,
+		"--session-id", "2026-06-07",
+		"--title", "The Black Cabin",
+		"--remote",
+	}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	key := artifacts.S3SessionConfigKey(artifacts.S3SessionPrefix("dnd", "sample-campaign", "2026-06-07"))
+	obj, ok := fake.Objects[key]
+	if !ok {
+		t.Fatalf("remote session key %q not uploaded; objects=%v", key, fake.Objects)
+	}
+	if !strings.Contains(string(obj.Data), `session_id: "2026-06-07"`) || !strings.Contains(string(obj.Data), "prefix: audio/") {
+		t.Fatalf("remote session data = %q", string(obj.Data))
+	}
+	if storeInitCalls != 1 {
+		t.Fatalf("object store init calls = %d, want 1", storeInitCalls)
+	}
+}
+
+func TestExecuteLockAndUnlockUseRemoteLockStore(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{
+		"lock",
+		"--config", pipelinePath,
+		"--campaign", campaignPath,
+		"--session", sessionPath,
+		"--reason", "manual edit",
+		"narratio.transcript.trimmed",
+	}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("lock exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	key := artifacts.S3SessionLocksKey(artifacts.S3SessionPrefix("dnd", "sample-campaign", "2026-05-03"))
+	obj, ok := fake.Objects[key]
+	if !ok {
+		t.Fatalf("remote locks key %q not uploaded", key)
+	}
+	if !strings.Contains(string(obj.Data), "source: narratio.transcript.trimmed") || !strings.Contains(string(obj.Data), "reason: manual edit") {
+		t.Fatalf("lock store data = %q", string(obj.Data))
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	code = Execute([]string{
+		"unlock",
+		"--config", pipelinePath,
+		"--campaign", campaignPath,
+		"--session", sessionPath,
+		"narratio.transcript.trimmed",
+	}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("unlock exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	store, err := config.LoadArchiveLockStoreBytes("locks.yml", fake.Objects[key].Data, nil)
+	if err != nil {
+		t.Fatalf("LoadArchiveLockStoreBytes() error = %v", err)
+	}
+	if len(store.Locks) != 0 {
+		t.Fatalf("locks after unlock = %#v, want empty", store.Locks)
+	}
+	if storeInitCalls != 2 {
+		t.Fatalf("object store init calls = %d, want 2", storeInitCalls)
+	}
+}
+
+func TestExecuteArtifactsListRemoteReportsPromotedAvailability(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	trimmedKey := artifacts.S3PromotedArtifactKey(
+		artifacts.S3SessionPrefix("dnd", "sample-campaign", "2026-05-03"),
+		"transcripts/trimmed.json",
+	)
+	fake.SeedObject(storage.FakeObject{Key: trimmedKey, Data: []byte(`{"segments":[]}`)})
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{
+		"artifacts", "list",
+		"--config", pipelinePath,
+		"--campaign", campaignPath,
+		"--session", sessionPath,
+		"--remote",
+	}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "narratio.transcript.trimmed remote=promoted") {
+		t.Fatalf("stdout = %q, want promoted remote availability", stdout.String())
+	}
+}
+
+func TestExecuteArchiveLoadsRemoteLocks(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidArchiveConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	lockKey := artifacts.S3SessionLocksKey(artifacts.S3SessionPrefix("dnd", "sample-campaign", "2026-05-03"))
+	fake.SeedObject(storage.FakeObject{Key: lockKey, Data: []byte("locks:\n  - source: narratio.transcript.trimmed\n    reason: remote review\n")})
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+
+	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
+	for _, stageName := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze"} {
+		// The archive stage only checks the manifest statuses and source files.
+		_ = stageName
+	}
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "trimmed.json"), `{"segments":[]}`)
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"run-stage", "--config", pipelinePath, "--campaign", campaignPath, "--session", sessionPath, "--force", "archive"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	promotedKey := artifacts.S3PromotedArtifactKey(artifacts.S3SessionPrefix("dnd", "sample-campaign", "2026-05-03"), "transcripts/trimmed.json")
+	if _, ok := fake.Objects[promotedKey]; ok {
+		t.Fatalf("locked promoted key %q was uploaded", promotedKey)
+	}
+}
+
+func writeValidArchiveConfigFiles(t *testing.T, workspaceRoot string) (string, string, string) {
+	t.Helper()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	data, err := os.ReadFile(pipelinePath)
+	if err != nil {
+		t.Fatalf("read pipeline: %v", err)
+	}
+	updated := strings.Replace(string(data), "upload_run: false", "upload_run: true", 1)
+	if err := os.WriteFile(pipelinePath, []byte(updated), 0o644); err != nil {
+		t.Fatalf("write pipeline: %v", err)
+	}
+	ctx := context.Background()
+	cfg, err := config.LoadWithSessionOptions(pipelinePath, campaignPath, sessionPath, config.SessionLoadOptions{})
+	if err != nil {
+		t.Fatalf("LoadWithSessionOptions() error = %v", err)
+	}
+	store := &manifest.LocalStore{}
+	m := manifest.New("2026-05-03", nowUTC())
+	m.Campaign = "sample-campaign"
+	m.RunID = "20260521T160000Z-test"
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "analyze"} {
+		m.MarkStageSucceeded(name, nowUTC(), nil)
+	}
+	path := artifacts.SessionManifestPathForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	if err := store.Save(ctx, path, m); err != nil {
+		t.Fatalf("save manifest: %v", err)
+	}
+	runManifestPath := artifacts.SessionRunManifestPathForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, m.RunID)
+	if err := os.MkdirAll(filepath.Dir(runManifestPath), 0o755); err != nil {
+		t.Fatalf("mkdir run manifest: %v", err)
+	}
+	if err := os.WriteFile(runManifestPath, []byte("{}\n"), 0o644); err != nil {
+		t.Fatalf("write run manifest: %v", err)
+	}
+	return pipelinePath, campaignPath, sessionPath
+}
--- a/internal/app/remote_locks.go
+++ b/internal/app/remote_locks.go
@@ -0,0 +1,157 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+type effectiveLocks struct {
+	Static []config.ArchiveLockRule
+	Remote []config.ArchiveLockRule
+	All    []config.ArchiveLockRule
+	Key    string
+}
+
+func remoteLocksKey(cfg *config.Config) (string, error) {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
+		return "", fmt.Errorf("resolved config is required")
+	}
+	if cfg.Pipeline.Storage.S3 == nil {
+		return "", fmt.Errorf("pipeline.storage.s3 configuration is required")
+	}
+	sessionPrefix := artifacts.S3SessionPrefix(
+		cfg.Pipeline.Storage.S3.RootPrefix,
+		cfg.Session.Campaign,
+		cfg.Session.SessionID,
+	)
+	return artifacts.S3SessionLocksKey(sessionPrefix), nil
+}
+
+func loadRemoteLockStore(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*config.ArchiveLockStore, string, error) {
+	key, err := remoteLocksKey(cfg)
+	if err != nil {
+		return nil, "", err
+	}
+	exists, err := store.Exists(ctx, key)
+	if err != nil {
+		return nil, key, fmt.Errorf("check remote locks %q: %w", key, err)
+	}
+	if !exists {
+		return &config.ArchiveLockStore{}, key, nil
+	}
+	tmp, err := downloadObjectToTemp(ctx, store, key, "narratio-locks-*.yml")
+	if err != nil {
+		return nil, key, fmt.Errorf("download remote locks %q: %w", key, err)
+	}
+	defer func() { _ = os.Remove(tmp) }()
+	data, err := os.ReadFile(tmp)
+	if err != nil {
+		return nil, key, fmt.Errorf("read remote locks %q: %w", key, err)
+	}
+	lockStore, err := config.LoadArchiveLockStoreBytes("s3://"+s3BucketName(cfg.Pipeline)+"/"+key, data, cfg.Pipeline.Scriptorium)
+	if err != nil {
+		return nil, key, err
+	}
+	return lockStore, key, nil
+}
+
+func loadEffectiveLocks(ctx context.Context, cfg *config.Config, store storage.ObjectStore) (*effectiveLocks, error) {
+	staticLocks := staticArchiveLocks(cfg)
+	if store == nil {
+		return &effectiveLocks{
+			Static: staticLocks,
+			All:    append([]config.ArchiveLockRule(nil), staticLocks...),
+		}, nil
+	}
+	lockStore, key, err := loadRemoteLockStore(ctx, cfg, store)
+	if err != nil {
+		return nil, err
+	}
+	remoteLocks := append([]config.ArchiveLockRule(nil), lockStore.Locks...)
+	return &effectiveLocks{
+		Static: staticLocks,
+		Remote: remoteLocks,
+		All:    config.MergeArchiveLockRules(staticLocks, remoteLocks),
+		Key:    key,
+	}, nil
+}
+
+func staticArchiveLocks(cfg *config.Config) []config.ArchiveLockRule {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Archive == nil {
+		return nil
+	}
+	return append([]config.ArchiveLockRule(nil), cfg.Pipeline.Archive.Locks...)
+}
+
+func applyEffectiveLocks(cfg *config.Config, locks []config.ArchiveLockRule) {
+	if cfg == nil || cfg.Pipeline == nil {
+		return
+	}
+	if cfg.Pipeline.Archive == nil {
+		cfg.Pipeline.Archive = &config.ArchiveConfig{}
+	}
+	cfg.Pipeline.Archive.Locks = append([]config.ArchiveLockRule(nil), locks...)
+}
+
+func uploadRemoteLockStore(ctx context.Context, store storage.ObjectStore, key string, lockStore *config.ArchiveLockStore) error {
+	data, err := config.MarshalArchiveLockStore(lockStore)
+	if err != nil {
+		return err
+	}
+	tmp, err := os.CreateTemp("", "narratio-locks-upload-*.yml")
+	if err != nil {
+		return fmt.Errorf("create lock store temp file: %w", err)
+	}
+	tmpPath := tmp.Name()
+	defer func() { _ = os.Remove(tmpPath) }()
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("write lock store temp file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close lock store temp file: %w", err)
+	}
+	if _, err := store.Upload(ctx, tmpPath, key, storage.UploadOptions{ContentType: "application/x-yaml; charset=utf-8"}); err != nil {
+		return fmt.Errorf("upload remote locks %q: %w", key, err)
+	}
+	return nil
+}
+
+func lockSourceSet(locks []config.ArchiveLockRule) map[string]config.ArchiveLockRule {
+	out := make(map[string]config.ArchiveLockRule, len(locks))
+	for _, lock := range locks {
+		source := strings.TrimSpace(lock.Source)
+		if source == "" {
+			continue
+		}
+		lock.Source = source
+		lock.Reason = strings.TrimSpace(lock.Reason)
+		out[source] = lock
+	}
+	return out
+}
+
+func writeLocalFile(path string, data []byte, force bool) error {
+	cleaned := filepath.Clean(strings.TrimSpace(path))
+	if cleaned == "" || cleaned == "." {
+		return fmt.Errorf("output path is required")
+	}
+	if !force {
+		if _, err := os.Stat(cleaned); err == nil {
+			return fmt.Errorf("output file %q already exists; pass --force to overwrite", cleaned)
+		} else if err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("check output file %q: %w", cleaned, err)
+		}
+	}
+	if err := os.MkdirAll(filepath.Dir(cleaned), 0o755); err != nil {
+		return fmt.Errorf("create output directory: %w", err)
+	}
+	return os.WriteFile(cleaned, data, 0o644)
+}
--- a/internal/app/runner.go
+++ b/internal/app/runner.go
@@ -87,12 +87,19 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
 		env.Storage = &storage.NoopBackend{}
 	}
 	if env.ObjectStore == nil && needsObjectStoreForRun(env.Config, stages) {
-		objectStore, err := storage.NewObjectStoreFromConfig(ctx, env.Config)
+		objectStore, err := newObjectStoreFromConfigFn(ctx, env.Config)
 		if err != nil {
 			return nil, fmt.Errorf("initialize object store backend: %w", err)
 		}
 		env.ObjectStore = objectStore
 	}
+	if needsRemoteLocksForRun(env.Config, stages) {
+		locks, err := loadEffectiveLocks(ctx, env.Config, env.ObjectStore)
+		if err != nil {
+			return nil, fmt.Errorf("load remote archive locks: %w", err)
+		}
+		applyEffectiveLocks(env.Config, locks.All)
+	}
 	if env.Notifier == nil {
 		env.Notifier = &notify.NoopSender{}
 	}
@@ -576,6 +583,32 @@ func needsObjectStoreForRun(cfg *config.Config, stages []stage.Stage) bool {
 	return true
 }

+func needsRemoteLocksForRun(cfg *config.Config, stages []stage.Stage) bool {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
+		return false
+	}
+	archiveRequested := false
+	for _, s := range stages {
+		if s != nil && s.Name() == "archive" {
+			archiveRequested = true
+			break
+		}
+	}
+	if !archiveRequested {
+		return false
+	}
+	if cfg.Pipeline.Archive == nil {
+		return false
+	}
+	if cfg.Pipeline.Archive.Enabled != nil && !*cfg.Pipeline.Archive.Enabled {
+		return false
+	}
+	if cfg.Pipeline.Archive.UploadRun != nil && !*cfg.Pipeline.Archive.UploadRun {
+		return false
+	}
+	return cfg.Pipeline.Storage.S3 != nil
+}
+
 func configuredScriptoriumArtifacts(cfg *config.Config) map[string]config.ScriptoriumArtifactConfig {
 	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Scriptorium == nil {
 		return nil
--- a/internal/app/status.go
+++ b/internal/app/status.go
@@ -1,67 +0,0 @@
-package app
-
-import (
-	"context"
-	"flag"
-	"fmt"
-	"io"
-	"sort"
-
-	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
-)
-
-// Status reads and prints stage statuses from an existing manifest.
-func Status(ctx context.Context, args []string, out io.Writer) error {
-	fs := flag.NewFlagSet("status", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-
-	var manifestPath string
-	fs.StringVar(&manifestPath, "manifest", "", "path to manifest.json")
-
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("status: invalid flags: %w", err)
-	}
-	if fs.NArg() != 0 {
-		return fmt.Errorf("status: unexpected positional arguments")
-	}
-	if manifestPath == "" {
-		return fmt.Errorf("status: --manifest is required")
-	}
-
-	store := &manifest.LocalStore{}
-	m, err := store.Load(ctx, manifestPath)
-	if err != nil {
-		return fmt.Errorf("status: %w", err)
-	}
-
-	if _, err := fmt.Fprintf(out, "session_id: %s\n", m.SessionID); err != nil {
-		return err
-	}
-	if _, err := fmt.Fprintf(out, "updated_at: %s\n", m.UpdatedAt.UTC().Format("2006-01-02T15:04:05Z07:00")); err != nil {
-		return err
-	}
-
-	if len(m.Stages) == 0 {
-		_, err := fmt.Fprintln(out, "stages: no stages recorded")
-		return err
-	}
-
-	if _, err := fmt.Fprintln(out, "stages:"); err != nil {
-		return err
-	}
-
-	names := make([]string, 0, len(m.Stages))
-	for name := range m.Stages {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-
-	for _, name := range names {
-		status := m.Stages[name].Status
-		if _, err := fmt.Fprintf(out, "- %s: %s\n", name, status); err != nil {
-			return err
-		}
-	}
-
-	return nil
-}
--- a/internal/artifacts/s3_keys.go
+++ b/internal/artifacts/s3_keys.go
@@ -40,6 +40,12 @@ func S3SessionConfigKey(sessionPrefix string) string {
 	return path.Join(strings.TrimSuffix(cleanS3Key(sessionPrefix), "/"), "session.yml")
 }

+// S3SessionLocksKey returns the mutable session lock store key.
+// Format: {session_prefix}/locks.yml
+func S3SessionLocksKey(sessionPrefix string) string {
+	return path.Join(strings.TrimSuffix(cleanS3Key(sessionPrefix), "/"), "locks.yml")
+}
+
 // S3CurrentManifestKey returns the current manifest pointer key.
 // Format: {session_prefix}/current/manifest.json
 func S3CurrentManifestKey(sessionPrefix string) string {
--- a/internal/artifacts/s3_keys_test.go
+++ b/internal/artifacts/s3_keys_test.go
@@ -22,6 +22,11 @@ func TestS3KeyConstruction(t *testing.T) {
 		t.Fatalf("session config key = %q", sessionConfigKey)
 	}

+	locksKey := S3SessionLocksKey(`dnd\campaigns\forsaken\sessions\2026-04-19\`)
+	if locksKey != "dnd/campaigns/forsaken/sessions/2026-04-19/locks.yml" {
+		t.Fatalf("locks key = %q", locksKey)
+	}
+
 	runPrefix := S3RunPrefix(sessionPrefix, runID)
 	wantRunPrefix := "dnd/campaigns/forsaken/sessions/2026-04-19/runs/" + runID + "/"
 	if runPrefix != wantRunPrefix {
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -112,6 +112,11 @@ type ArchiveLockRule struct {
 	Reason string `yaml:"reason"`
 }

+// ArchiveLockStore is the mutable per-session remote lock store.
+type ArchiveLockStore struct {
+	Locks []ArchiveLockRule `yaml:"locks"`
+}
+
 // WhisperXConfig configures WhisperX adapter settings.
 type WhisperXConfig struct {
 	TranscribeURL string `yaml:"transcribe_url"`
--- a/internal/config/load.go
+++ b/internal/config/load.go
@@ -85,6 +85,33 @@ func LoadSessionBytesWithOptions(label string, data []byte, opts SessionLoadOpti
 	return &cfg, nil
 }

+// LoadArchiveLockStoreBytes loads a mutable session lock store with strict
+// field checking and source validation.
+func LoadArchiveLockStoreBytes(label string, data []byte, scriptorium *ScriptoriumConfig) (*ArchiveLockStore, error) {
+	var store ArchiveLockStore
+	if err := decodeStrictYAMLFromReader("archive lock store", label, strings.NewReader(string(data)), &store); err != nil {
+		return nil, fmt.Errorf("load archive lock store: %w", err)
+	}
+	locks, err := ValidateArchiveLockRules(store.Locks, scriptorium, "locks")
+	if err != nil {
+		return nil, fmt.Errorf("load archive lock store: %w", err)
+	}
+	store.Locks = locks
+	return &store, nil
+}
+
+// MarshalArchiveLockStore serializes a mutable lock store as strict-compatible YAML.
+func MarshalArchiveLockStore(store *ArchiveLockStore) ([]byte, error) {
+	if store == nil {
+		store = &ArchiveLockStore{}
+	}
+	data, err := yaml.Marshal(store)
+	if err != nil {
+		return nil, fmt.Errorf("marshal archive lock store: %w", err)
+	}
+	return data, nil
+}
+
 // Load loads and resolves combined pipeline, campaign, and session configuration.
 // Passing only a session path is supported for package-internal compatibility;
 // in that form campaign.yml is expected next to the session file.
--- a/internal/config/storage_archive_test.go
+++ b/internal/config/storage_archive_test.go
@@ -395,6 +395,54 @@ archive:
 	}
 }

+func TestArchiveLockStoreBytesStrictDecodeAndValidation(t *testing.T) {
+	store, err := LoadArchiveLockStoreBytes("locks.yml", []byte(`locks:
+  - source: narratio.transcript.trimmed
+    reason: reviewed
+`), nil)
+	if err != nil {
+		t.Fatalf("LoadArchiveLockStoreBytes() error = %v", err)
+	}
+	if len(store.Locks) != 1 || store.Locks[0].Source != "narratio.transcript.trimmed" || store.Locks[0].Reason != "reviewed" {
+		t.Fatalf("locks = %#v", store.Locks)
+	}
+
+	_, err = LoadArchiveLockStoreBytes("locks.yml", []byte(`locks:
+  - source: narratio.transcript.trimmed
+    dest: transcripts/trimmed.json
+`), nil)
+	if err == nil || !strings.Contains(err.Error(), "strict decode failed") {
+		t.Fatalf("unknown field error = %v, want strict decode failed", err)
+	}
+
+	_, err = LoadArchiveLockStoreBytes("locks.yml", []byte(`locks:
+  - source: narratio.transcript.trimmed
+  - source: narratio.transcript.trimmed
+`), nil)
+	if err == nil || !strings.Contains(err.Error(), "duplicates another archive lock source") {
+		t.Fatalf("duplicate error = %v", err)
+	}
+}
+
+func TestMergeArchiveLockRulesStaticWins(t *testing.T) {
+	merged := MergeArchiveLockRules(
+		[]ArchiveLockRule{{Source: "narratio.transcript.trimmed", Reason: "static"}},
+		[]ArchiveLockRule{
+			{Source: "narratio.transcript.trimmed", Reason: "remote"},
+			{Source: "narratio.transcript.full", Reason: "remote full"},
+		},
+	)
+	if len(merged) != 2 {
+		t.Fatalf("merged len = %d, want 2: %#v", len(merged), merged)
+	}
+	if merged[0].Source != "narratio.transcript.trimmed" || merged[0].Reason != "static" {
+		t.Fatalf("merged[0] = %#v, want static lock", merged[0])
+	}
+	if merged[1].Source != "narratio.transcript.full" {
+		t.Fatalf("merged[1] = %#v, want remote full lock", merged[1])
+	}
+}
+
 func TestSessionAudioS3Validation(t *testing.T) {
 	tests := []struct {
 		name        string
--- a/internal/config/validate.go
+++ b/internal/config/validate.go
@@ -152,24 +152,67 @@ func validateArchive(cfg *ArchiveConfig, scriptorium *ScriptoriumConfig) error {
 		}
 		seenDest[normalizedDest] = struct{}{}
 	}
+	locks, err := ValidateArchiveLockRules(cfg.Locks, scriptorium, "pipeline.archive.locks")
+	if err != nil {
+		return err
+	}
+	cfg.Locks = locks
+	return nil
+}
+
+// ValidateArchiveLockRules validates and normalizes source-based archive locks.
+func ValidateArchiveLockRules(locks []ArchiveLockRule, scriptorium *ScriptoriumConfig, label string) ([]ArchiveLockRule, error) {
 	seenLocks := map[string]struct{}{}
-	for i, item := range cfg.Locks {
-		prefix := fmt.Sprintf("pipeline.archive.locks[%d]", i)
+	out := make([]ArchiveLockRule, 0, len(locks))
+	if strings.TrimSpace(label) == "" {
+		label = "archive.locks"
+	}
+	for i, item := range locks {
+		prefix := fmt.Sprintf("%s[%d]", label, i)
 		source := strings.TrimSpace(item.Source)
 		if source == "" {
-			return fmt.Errorf("%s.source is required", prefix)
+			return nil, fmt.Errorf("%s.source is required", prefix)
 		}
 		if _, err := archiveSourceKnown(source, scriptorium); err != nil {
-			return fmt.Errorf("%s.source %q is unsupported: %w", prefix, item.Source, err)
+			return nil, fmt.Errorf("%s.source %q is unsupported: %w", prefix, item.Source, err)
 		}
 		if _, ok := seenLocks[source]; ok {
-			return fmt.Errorf("%s.source %q duplicates another archive lock source", prefix, source)
+			return nil, fmt.Errorf("%s.source %q duplicates another archive lock source", prefix, source)
 		}
 		seenLocks[source] = struct{}{}
-		cfg.Locks[i].Source = source
-		cfg.Locks[i].Reason = strings.TrimSpace(item.Reason)
+		out = append(out, ArchiveLockRule{
+			Source: source,
+			Reason: strings.TrimSpace(item.Reason),
+		})
 	}
-	return nil
+	return out, nil
+}
+
+// MergeArchiveLockRules returns the union of static and remote locks. Static
+// locks win when both sources contain the same lock.
+func MergeArchiveLockRules(staticLocks, remoteLocks []ArchiveLockRule) []ArchiveLockRule {
+	out := make([]ArchiveLockRule, 0, len(staticLocks)+len(remoteLocks))
+	seen := map[string]struct{}{}
+	for _, item := range staticLocks {
+		source := strings.TrimSpace(item.Source)
+		if source == "" {
+			continue
+		}
+		out = append(out, ArchiveLockRule{Source: source, Reason: strings.TrimSpace(item.Reason)})
+		seen[source] = struct{}{}
+	}
+	for _, item := range remoteLocks {
+		source := strings.TrimSpace(item.Source)
+		if source == "" {
+			continue
+		}
+		if _, ok := seen[source]; ok {
+			continue
+		}
+		out = append(out, ArchiveLockRule{Source: source, Reason: strings.TrimSpace(item.Reason)})
+		seen[source] = struct{}{}
+	}
+	return out
 }

 func archiveSourceKnown(source string, scriptorium *ScriptoriumConfig) (string, error) {